Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.eclipse.jface.text
Interface IDocument

All Known Implementing Classes:
  AbstractDocument

public interface IDocument

An `IDocument` represents text providing support for

- text manipulation
- positions
- partitions
- line information
- document change listeners
- document partition change listeners

A document allows to set its content and to manipulate it. For manipulation a document provides the `replace` method which substitutes a given string for a specified text range in the document. On each document change, all registered document listeners are informed exactly once. Positions are stickers to the document's text that are updated when the document is changed. Positions are updated by `IPositionUpdater`s. Position updaters are managed as a list. The list defines the sequence in which position updaters are invoked. This way, position updaters may rely on each other. Positions are grouped into categories. A category is a ordered list of positions. the document defines the order of position in a category based on the position's offset based on the implementation of the method `computeIndexInCategory`. Each document must support a default position category whose name is specified by this interface.

A document can be considered consisting of a sequence of not overlapping partitions. A partition is defined by its offset, its length, and its type. Partitions are updated on every document manipulation and ensured to be up-to-date when the document listeners are informed. A document uses an `IDocumentPartitioner` to manage its partitions. A document may be unpartitioned which happens when there is no partitioner. In this case, the document is considered as one single partition of a default type. The default type is specified by this interface. If a document change changes the document's partitioning all registered partitioning listeners are informed exactly once. The extension interface `IDocumentExtension3` introduced in version 3.0 extends the concept of partitions and allows a document to not only manage one but multiple partitioning. Each partitioning has an id which must be used to refer to a particular partitioning.

An `IDocument` provides methods to map line numbers and character positions onto each other based on the document's line delimiters. When moving text between documents using different line delimiters, the text must be converted to use the target document's line delimiters.

`IDocument` throws `BadLocationException` if the parameters of queries or manipulation requests are not inside the bounds of the document. The purpose of this style of exception handling is

- prepare document for multi-thread access
- allow clients to implement backtracking recovery methods
- prevent clients from up-front contract checking when dealing with documents.

A document support for searching has deprecated since version 3.0. The recommended way for searching is to use a `FindReplaceDocumentAdapter`.

In order to provide backward compatibility for clients of `IDocument`, extension interfaces are used to provide a means of evolution. The following extension interfaces exist:

- `IDocumentExtension` since version 2.0 introducing the concept of post notification replaces in order to allow document listeners to manipulate the document while receiving a document change notification
- `IDocumentExtension2` since version 2.1 introducing configuration methods for post notification replaces and document change notification.
- `IDocumentExtension3` since version 3.0 replacing the original partitioning concept by allowing multiple partitionings at the same time and introducing zero- length partitions in conjunction with the distinction between open and closed partitions.

Clients may implement this interface and its extension interfaces or use the default implementation provided by `AbstractDocument` and `Document`.

See Also:
  `IDocumentExtension`, `IDocumentExtension2`, `IDocumentExtension3`, `Position`, `IPositionUpdater`, `IDocumentPartitioner`, `ILineTracker`, `IDocumentListener`, `IDocumentPartitioningListener`

Field Summary
`static String` | `DEFAULT_CATEGORY` The identifier of the default position category.
`static String` | `DEFAULT_CONTENT_TYPE` The identifier of the default partition content type.

Method Summary
`void` | `addDocumentListener(IDocumentListener listener)` Registers the document listener with the document.
`void` | `addDocumentPartitioningListener(IDocumentPartitioningListener listener)` Registers the document partitioning listener with the document.
`void` | `addPosition(Position position)` Adds the position to the document's default position category.
`void` | `addPosition(String category, Position position)` Adds the position to the specified position category of the document.
`void` | `addPositionCategory(String category)` Adds a new position category to the document.
`void` | `addPositionUpdater(IPositionUpdater updater)` Appends a new position updater to the document's list of position updaters.
`void` | `addPrenotifiedDocumentListener(IDocumentListener documentAdapter)` Adds the given document listener as one which is notified before those document listeners added with `addDocumentListener` are notified.
`int` | `computeIndexInCategory(String category, int offset)` Computes the index at which a `Position` with the specified offset would be inserted into the given category.
`int` | `computeNumberOfLines(String text)` Computes the number of lines in the given text.
`ITypedRegion[]` | `computePartitioning(int offset, int length)` Computes the partitioning of the given document range using the document's partitioner.
`boolean` | `containsPosition(String category, int offset, int length)` Determines whether a position described by the parameters is managed by this document.
`boolean` | `containsPositionCategory(String category)` Checks the presence of the specified position category.
`String` | `get()` Returns this document's complete text.
`String` | `get(int offset, int length)` Returns this document's text for the specified range.
`char` | `getChar(int offset)` Returns the character at the given document offset in this document.
`String` | `getContentType(int offset)` Returns the type of the document partition containing the given offset.
`IDocumentPartitioner` | `getDocumentPartitioner()` Returns this document's partitioner.
`String[]` | `getLegalContentTypes()` Returns the set of legal content types of document partitions.
`String[]` | `getLegalLineDelimiters()` Returns the document's legal line delimiters.
`int` | `getLength()` Returns the number of characters in this document.
`String` | `getLineDelimiter(int line)` Returns the line delimiter of that line or `null` if the line is not closed with a line delimiter.
`IRegion` | `getLineInformation(int line)` Returns a description of the specified line.
`IRegion` | `getLineInformationOfOffset(int offset)` Returns a description of the line at the given offset.
`int` | `getLineLength(int line)` Returns the length of the given line including the line's delimiter.
`int` | `getLineOffset(int line)` Determines the offset of the first character of the given line.
`int` | `getLineOfOffset(int offset)` Returns the number of the line at which the character of the specified position is located.
`int` | `getNumberOfLines()` Returns the number of lines in this document
`int` | `getNumberOfLines(int offset, int length)` Returns the number of lines which are occupied by a given text range.
`ITypedRegion` | `getPartition(int offset)` Returns the document partition in which the position is located.
`String[]` | `getPositionCategories()` Returns all position categories of this document.
`Position[]` | `getPositions(String category)` Returns all positions of the given position category.
`IPositionUpdater[]` | `getPositionUpdaters()` Returns the list of position updaters attached to the document.
`void` | `insertPositionUpdater(IPositionUpdater updater, int index)` Inserts the position updater at the specified index in the document's list of position updaters.
`void` | `removeDocumentListener(IDocumentListener listener)` Removes the listener from the document's list of document listeners.
`void` | `removeDocumentPartitioningListener(IDocumentPartitioningListener listener)` Removes the listener from this document's list of document partitioning listeners.
`void` | `removePosition(Position position)` Removes the given position from the document's default position category.
`void` | `removePosition(String category, Position position)` Removes the given position from the specified position category.
`void` | `removePositionCategory(String category)` Deletes the position category from the document.
`void` | `removePositionUpdater(IPositionUpdater updater)` Removes the position updater from the document's list of position updaters.
`void` | `removePrenotifiedDocumentListener(IDocumentListener documentAdapter)` Removes the given document listener from the document's list of pre-notified document listeners.
`void` | `replace(int offset, int length, String text)` Substitutes the given text for the specified document range.
`int` | `search(int startOffset, String findString, boolean forwardSearch, boolean caseSensitive, boolean wholeWord)` Deprecated. as of 3.0 search is provided by `FindReplaceDocumentAdapter`
`void` | `set(String text)` Replaces the content of the document with the given text.
`void` | `setDocumentPartitioner(IDocumentPartitioner partitioner)` Sets this document's partitioner.

Field Detail

### DEFAULT_CATEGORY

    public static final String DEFAULT_CATEGORY

  The identifier of the default position category.

  See Also:
    Constant Field Values

### DEFAULT_CONTENT_TYPE

    public static final String DEFAULT_CONTENT_TYPE

  The identifier of the default partition content type.

  See Also:
    Constant Field Values

Method Detail

### getChar

    public char getChar(int offset)
                 throws BadLocationException

  Returns the character at the given document offset in this document.

  Parameters:
    `offset` - a document offset
  Returns:
    the character at the offset
  Throws:
    `BadLocationException` - if the offset is invalid in this document

### getLength

    public int getLength()

  Returns the number of characters in this document.

  Returns:
    the number of characters in this document

### get

    public String get()

  Returns this document's complete text.

  Returns:
    the document's complete text

### get

    public String get(int offset,
                      int length)
               throws BadLocationException

  Returns this document's text for the specified range.

  Parameters:
    `offset` - the document offset
    `length` - the length of the specified range
  Returns:
    the document's text for the specified range
  Throws:
    `BadLocationException` - if the range is invalid in this document

### set

    public void set(String text)

  Replaces the content of the document with the given text. Sends a `DocumentEvent` to all registered `IDocumentListener`. This method is a convenience method for `replace(0, getLength(), text)`.

  Parameters:
    `text` - the new content of the document
  See Also:
    `DocumentEvent`, `IDocumentListener`

### replace

    public void replace(int offset,
                        int length,
                        String text)
                 throws BadLocationException

  Substitutes the given text for the specified document range. Sends a `DocumentEvent` to all registered `IDocumentListener`.

  Parameters:
    `offset` - the document offset
    `length` - the length of the specified range
    `text` - the substitution text
  Throws:
    `BadLocationException` - if the offset is invalid in this document
  See Also:
    `DocumentEvent`, `IDocumentListener`

### addDocumentListener

    public void addDocumentListener(IDocumentListener listener)

  Registers the document listener with the document. After registration the IDocumentListener is informed about each change of this document. If the listener is already registered nothing happens.

  An `IDocumentListener` may call back to this method when being inside a document notification.

  Parameters:
    `listener` - the listener to be registered

### removeDocumentListener

    public void removeDocumentListener(IDocumentListener listener)

  Removes the listener from the document's list of document listeners. If the listener is not registered with the document nothing happens.

  An `IDocumentListener` may call back to this method when being inside a document notification.

  Parameters:
    `listener` - the listener to be removed

### addPrenotifiedDocumentListener

    public void addPrenotifiedDocumentListener(IDocumentListener documentAdapter)

  Adds the given document listener as one which is notified before those document listeners added with `addDocumentListener` are notified. If the given listener is also registered using `addDocumentListener` it will be notified twice. If the listener is already registered nothing happens.

  This method is not for public use.

  Parameters:
    `documentAdapter` - the listener to be added as pre-notified document listener
  See Also:
    `removePrenotifiedDocumentListener(IDocumentListener)`

### removePrenotifiedDocumentListener

    public void removePrenotifiedDocumentListener(IDocumentListener documentAdapter)

  Removes the given document listener from the document's list of pre-notified document listeners. If the listener is not registered with the document nothing happens.

  This method is not for public use.

  Parameters:
    `documentAdapter` - the listener to be removed
  See Also:
    `addPrenotifiedDocumentListener(IDocumentListener)`

### addPositionCategory

    public void addPositionCategory(String category)

  Adds a new position category to the document. If the position category already exists nothing happens.

  Parameters:
    `category` - the category to be added

### removePositionCategory

    public void removePositionCategory(String category)
                                throws BadPositionCategoryException

  Deletes the position category from the document. All positions in this category are thus deleted as well.

  Parameters:
    `category` - the category to be removed
  Throws:
    `BadPositionCategoryException` - if category is undefined in this document

### getPositionCategories

    public String[] getPositionCategories()

  Returns all position categories of this document. This includes the default position category.

  Returns:
    the document's position categories

### containsPositionCategory

    public boolean containsPositionCategory(String category)

  Checks the presence of the specified position category.

  Parameters:
    `category` - the category to check
  Returns:
    `true` if category is defined

### addPosition

    public void addPosition(Position position)
                     throws BadLocationException

  Adds the position to the document's default position category. This is a convenience method for `addPosition(DEFAULT_CATEGORY, position)`.

  Parameters:
    `position` - the position to be added
  Throws:
    `BadLocationException` - if position describes an invalid range in this document

### removePosition

    public void removePosition(Position position)

  Removes the given position from the document's default position category. This is a convenience method for `removePosition(DEFAULT_CATEGORY, position)`.

  Parameters:
    `position` - the position to be removed

### addPosition

    public void addPosition(String category,
                            Position position)
                     throws BadLocationException,
                            BadPositionCategoryException

  Adds the position to the specified position category of the document. A position that has been added to a position category is updated on each change applied to the document. Positions may be added multiple times. The order of the category is maintained.

  Parameters:
    `category` - the category to which to add
    `position` - the position to be added
  Throws:
    `BadLocationException` - if position describes an invalid range in this document
    `BadPositionCategoryException` - if the category is undefined in this document

### removePosition

    public void removePosition(String category,
                               Position position)
                        throws BadPositionCategoryException

  Removes the given position from the specified position category. If the position is not part of the specified category nothing happens. If the position has been added multiple times, only the first occurrence is deleted.

  Parameters:
    `category` - the category from which to delete
    `position` - the position to be deleted
  Throws:
    `BadPositionCategoryException` - if category is undefined in this document

### getPositions

    public Position[] getPositions(String category)
                            throws BadPositionCategoryException

  Returns all positions of the given position category. The positions are ordered according to the category's order. Manipulating this list does not affect the document, but manipulating the position does affect the document.

  Parameters:
    `category` - the category
  Returns:
    the list of all positions
  Throws:
    `BadPositionCategoryException` - if category is undefined in this document

### containsPosition

    public boolean containsPosition(String category,
                                    int offset,
                                    int length)

  Determines whether a position described by the parameters is managed by this document.

  Parameters:
    `category` - the category to check
    `offset` - the offset of the position to find
    `length` - the length of the position to find
  Returns:
    `true` if position is found

### computeIndexInCategory

    public int computeIndexInCategory(String category,
                                      int offset)
                               throws BadLocationException,
                                      BadPositionCategoryException

  Computes the index at which a `Position` with the specified offset would be inserted into the given category. As the ordering inside a category only depends on the offset, the index must be chosen to be the first of all positions with the same offset.

  Parameters:
    `category` - the category in which would be added
    `offset` - the position offset to be considered
  Returns:
    the index into the category
  Throws:
    `BadLocationException` - if offset is invalid in this document
    `BadPositionCategoryException` - if category is undefined in this document

### addPositionUpdater

    public void addPositionUpdater(IPositionUpdater updater)

  Appends a new position updater to the document's list of position updaters. Position updaters may be added multiple times.

  An `IPositionUpdater` may call back to this method when being inside a document notification.

  Parameters:
    `updater` - the updater to be added

### removePositionUpdater

    public void removePositionUpdater(IPositionUpdater updater)

  Removes the position updater from the document's list of position updaters. If the position updater has multiple occurrences only the first occurrence is removed. If the position updater is not registered with this document, nothing happens.

  An `IPositionUpdater` may call back to this method when being inside a document notification.

  Parameters:
    `updater` - the updater to be removed

### insertPositionUpdater

    public void insertPositionUpdater(IPositionUpdater updater,
                                      int index)

  Inserts the position updater at the specified index in the document's list of position updaters. Positions updaters may be inserted multiple times.

  An `IPositionUpdater` may call back to this method when being inside a document notification.

  Parameters:
    `updater` - the updater to be inserted
    `index` - the index in the document's updater list

### getPositionUpdaters

    public IPositionUpdater[] getPositionUpdaters()

  Returns the list of position updaters attached to the document.

  Returns:
    the list of position updaters

### getLegalContentTypes

    public String[] getLegalContentTypes()

  Returns the set of legal content types of document partitions. This set can be empty. The set can contain more content types than contained by the result of `getPartitioning(0, getLength())`.

  Use `IDocumentExtension3.getLegalContentTypes(String)` when the document supports multiple partitionings. In that case this method is equivalent to:

          IDocumentExtension3 extension= (IDocumentExtension3) document;
          return extension.getLegalContentTypes(IDocumentExtension3.DEFAULT_PARTITIONING);

  Returns:
    the set of legal content types

### getContentType

    public String getContentType(int offset)
                          throws BadLocationException

  Returns the type of the document partition containing the given offset. This is a convenience method for `getPartition(offset).getType()`.

  Use `IDocumentExtension3.getContentType(String, int, boolean)` when the document supports multiple partitionings. In that case this method is equivalent to:

          IDocumentExtension3 extension= (IDocumentExtension3) document;
          return extension.getContentTypes(IDocumentExtension3.DEFAULT_PARTITIONING, offset, false);

  Parameters:
    `offset` - the document offset
  Returns:
    the partition type
  Throws:
    `BadLocationException` - if offset is invalid in this document

### getPartition

    public ITypedRegion getPartition(int offset)
                              throws BadLocationException

  Returns the document partition in which the position is located.

  Use `IDocumentExtension3.getPartition(String, int, boolean)` when the document supports multiple partitionings. In that case this method is equivalent:

          IDocumentExtension3 extension= (IDocumentExtension3) document;
          return extension.getPartition(IDocumentExtension3.DEFAULT_PARTITIONING, offset, false);

  Parameters:
    `offset` - the document offset
  Returns:
    a specification of the partition
  Throws:
    `BadLocationException` - if offset is invalid in this document

### computePartitioning

    public ITypedRegion[] computePartitioning(int offset,
                                              int length)
                                       throws BadLocationException

  Computes the partitioning of the given document range using the document's partitioner.

  Use `IDocumentExtension3.computePartitioning(String, int, int, boolean)` when the document supports multiple partitionings. In that case this method is equivalent:

          IDocumentExtension3 extension= (IDocumentExtension3) document;
          return extension.computePartitioning(IDocumentExtension3.DEFAULT_PARTITIONING, offset, length, false);

  Parameters:
    `offset` - the document offset at which the range starts
    `length` - the length of the document range
  Returns:
    a specification of the range's partitioning
  Throws:
    `BadLocationException` - if the range is invalid in this document

### addDocumentPartitioningListener

    public void addDocumentPartitioningListener(IDocumentPartitioningListener listener)

  Registers the document partitioning listener with the document. After registration the document partitioning listener is informed about each partition change cause by a document manipulation or by changing the document's partitioner. If a document partitioning listener is also a document listener, the following notification sequence is guaranteed if a document manipulation changes the document partitioning:
  - listener.documentAboutToBeChanged(DocumentEvent);
  - listener.documentPartitioningChanged();
  - listener.documentChanged(DocumentEvent);
  If the listener is already registered nothing happens.

  An `IDocumentPartitioningListener` may call back to this method when being inside a document notification.

  Parameters:
    `listener` - the listener to be added

### removeDocumentPartitioningListener

    public void removeDocumentPartitioningListener(IDocumentPartitioningListener listener)

  Removes the listener from this document's list of document partitioning listeners. If the listener is not registered with the document nothing happens.

  An `IDocumentPartitioningListener` may call back to this method when being inside a document notification.

  Parameters:
    `listener` - the listener to be removed

### setDocumentPartitioner

    public void setDocumentPartitioner(IDocumentPartitioner partitioner)

  Sets this document's partitioner. The caller of this method is responsible for disconnecting the document's old partitioner from the document and to connect the new partitioner to the document. Informs all document partitioning listeners about this change.

  Use `IDocumentExtension3.setDocumentPartitioner(String, IDocumentPartitioner)` when the document supports multiple partitionings. In that case this method is equivalent to:

          IDocumentExtension3 extension= (IDocumentExtension3) document;
          extension.setDocumentPartitioner(IDocumentExtension3.DEFAULT_PARTITIONING, partitioner);

  Parameters:
    `partitioner` - the document's new partitioner
  See Also:
    `IDocumentPartitioningListener`

### getDocumentPartitioner

    public IDocumentPartitioner getDocumentPartitioner()

  Returns this document's partitioner.

  Use `IDocumentExtension3.getDocumentPartitioner(String)` when the document supports multiple partitionings. In that case this method is equivalent to:

          IDocumentExtension3 extension= (IDocumentExtension3) document;
          return extension.getDocumentPartitioner(IDocumentExtension3.DEFAULT_PARTITIONING);

  Returns:
    this document's partitioner

### getLineLength

    public int getLineLength(int line)
                      throws BadLocationException

  Returns the length of the given line including the line's delimiter.

  Parameters:
    `line` - the line of interest
  Returns:
    the length of the line
  Throws:
    `BadLocationException` - if the line number is invalid in this document

### getLineOfOffset

    public int getLineOfOffset(int offset)
                        throws BadLocationException

  Returns the number of the line at which the character of the specified position is located. The first line has the line number 0. A new line starts directly after a line delimiter. `(offset == document length)` is a valid argument although there is no corresponding character.

  Parameters:
    `offset` - the document offset
  Returns:
    the number of the line
  Throws:
    `BadLocationException` - if the offset is invalid in this document

### getLineOffset

    public int getLineOffset(int line)
                      throws BadLocationException

  Determines the offset of the first character of the given line.

  Parameters:
    `line` - the line of interest
  Returns:
    the document offset
  Throws:
    `BadLocationException` - if the line number is invalid in this document

### getLineInformation

    public IRegion getLineInformation(int line)
                               throws BadLocationException

  Returns a description of the specified line. The line is described by its offset and its length excluding the line's delimiter.

  Parameters:
    `line` - the line of interest
  Returns:
    a line description
  Throws:
    `BadLocationException` - if the line number is invalid in this document

### getLineInformationOfOffset

    public IRegion getLineInformationOfOffset(int offset)
                                       throws BadLocationException

  Returns a description of the line at the given offset. The description contains the offset and the length of the line excluding the line's delimiter.

  Parameters:
    `offset` - the offset whose line should be described
  Returns:
    a region describing the line
  Throws:
    `BadLocationException` - if offset is invalid in this document

### getNumberOfLines

    public int getNumberOfLines()

  Returns the number of lines in this document

  Returns:
    the number of lines in this document

### getNumberOfLines

    public int getNumberOfLines(int offset,
                                int length)
                         throws BadLocationException

  Returns the number of lines which are occupied by a given text range.

  Parameters:
    `offset` - the offset of the specified text range
    `length` - the length of the specified text range
  Returns:
    the number of lines occupied by the specified range
  Throws:
    `BadLocationException` - if specified range is invalid in this tracker

### computeNumberOfLines

    public int computeNumberOfLines(String text)

  Computes the number of lines in the given text. For a given implementer of this interface this method returns the same result as `set(text); getNumberOfLines()`.

  Parameters:
    `text` - the text whose number of lines should be computed
  Returns:
    the number of lines in the given text

### getLegalLineDelimiters

    public String[] getLegalLineDelimiters()

  Returns the document's legal line delimiters.

  Returns:
    the document's legal line delimiters

### getLineDelimiter

    public String getLineDelimiter(int line)
                            throws BadLocationException

  Returns the line delimiter of that line or `null` if the line is not closed with a line delimiter.

  Parameters:
    `line` - the line of interest
  Returns:
    the line's delimiter or `null` if line does not have a delimiter
  Throws:
    `BadLocationException` - if the line number is invalid in this document

### search

    public int search(int startOffset,
                      String findString,
                      boolean forwardSearch,
                      boolean caseSensitive,
                      boolean wholeWord)
               throws BadLocationException

  Deprecated. as of 3.0 search is provided by `FindReplaceDocumentAdapter`

  Returns the offset of a given search string in the document based on a set of search criteria.

  Parameters:
    `startOffset` - document offset at which search starts
    `findString` - the string to find
    `forwardSearch` - the search direction
    `caseSensitive` - indicates whether lower and upper case should be distinguished
    `wholeWord` - indicates whether the findString should be limited by white spaces as defined by Character.isWhiteSpace
  Returns:
    the offset of the first occurrence of findString based on the parameters or -1 if no match is found
  Throws:
    `BadLocationException` - if startOffset is an invalid document offset

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2000, 2004. All rights reserved.