Docjar: A Java Source and Docuemnt Enginecom.*    java.*    javax.*    org.*    all    new    plug-in

Quick Search    Search Deep
Overview  Package   Class  Use  Deprecated  Index 
Home >> All >> org >> eclipse >> jface >> [ text overview ]  PREV CLASS  NEXT CLASS
SUMMARY: JavaDoc of org.eclipse.jface.text.IDocument JAVADOC | Sourc code of org.eclipse.jface.text.IDocument SOURCE | Download org.eclipse.jface.text.IDocument DOWNLOAD | NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.eclipse.jface.text
Interface IDocument  view IDocument download IDocument.java

All Known Implementing Classes:
AbstractDocument
public interface IDocument

An IDocument represents text providing support for

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

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:

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

Field Summary
static java.lang.String DEFAULT_CATEGORY
          The identifier of the default position category.
static java.lang.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(java.lang.String category, Position position)
          Adds the position to the specified position category of the document.
 void addPositionCategory(java.lang.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(java.lang.String category, int offset)
          Computes the index at which a Position with the specified offset would be inserted into the given category.
 int computeNumberOfLines(java.lang.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(java.lang.String category, int offset, int length)
          Determines whether a position described by the parameters is managed by this document.
 boolean containsPositionCategory(java.lang.String category)
          Checks the presence of the specified position category.
 java.lang.String get()
          Returns this document's complete text.
 java.lang.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.
 java.lang.String getContentType(int offset)
          Returns the type of the document partition containing the given offset.
 IDocumentPartitioner getDocumentPartitioner()
          Returns this document's partitioner.
 java.lang.String[] getLegalContentTypes()
          Returns the set of legal content types of document partitions.
 java.lang.String[] getLegalLineDelimiters()
          Returns the document's legal line delimiters.
 int getLength()
          Returns the number of characters in this document.
 java.lang.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.
 java.lang.String[] getPositionCategories()
          Returns all position categories of this document.
 Position[] getPositions(java.lang.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(java.lang.String category, Position position)
          Removes the given position from the specified position category.
 void removePositionCategory(java.lang.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, java.lang.String text)
          Substitutes the given text for the specified document range.
 int search(int startOffset, java.lang.String findString, boolean forwardSearch, boolean caseSensitive, boolean wholeWord)
          Deprecated. as of 3.0 search is provided by FindReplaceDocumentAdapter
 void set(java.lang.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 java.lang.String DEFAULT_CATEGORY
The identifier of the default position category.

See Also:
Constant Field Values

DEFAULT_CONTENT_TYPE

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

getLength

public int getLength()
Returns the number of characters in this document.

get

public java.lang.String get()
Returns this document's complete text.

get

public java.lang.String get(int offset,
                            int length)
                     throws BadLocationException
Returns this document's text for the specified range.

set

public void set(java.lang.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).

replace

public void replace(int offset,
                    int length,
                    java.lang.String text)
             throws BadLocationException
Substitutes the given text for the specified document range. Sends a DocumentEvent to all registered 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.

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.

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.

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.

addPositionCategory

public void addPositionCategory(java.lang.String category)
Adds a new position category to the document. If the position category already exists nothing happens.

removePositionCategory

public void removePositionCategory(java.lang.String category)
                            throws BadPositionCategoryException
Deletes the position category from the document. All positions in this category are thus deleted as well.

getPositionCategories

public java.lang.String[] getPositionCategories()
Returns all position categories of this document. This includes the default position category.

containsPositionCategory

public boolean containsPositionCategory(java.lang.String category)
Checks the presence of the specified position category.

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

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

addPosition

public void addPosition(java.lang.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.

removePosition

public void removePosition(java.lang.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.

getPositions

public Position[] getPositions(java.lang.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.

containsPosition

public boolean containsPosition(java.lang.String category,
                                int offset,
                                int length)
Determines whether a position described by the parameters is managed by this document.

computeIndexInCategory

public int computeIndexInCategory(java.lang.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.

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.

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.

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.

getPositionUpdaters

public IPositionUpdater[] getPositionUpdaters()
Returns the list of position updaters attached to the document.

getLegalContentTypes

public java.lang.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) 55 when the document supports multiple partitionings. In that case this method is equivalent to: 

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

getContentType

public java.lang.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) 55 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);

getPartition

public ITypedRegion getPartition(int offset)
                          throws BadLocationException
Returns the document partition in which the position is located.

Use IDocumentExtension3.getPartition(String, int, boolean) 55 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);

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) 55 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);

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.

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.

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) 55 when the document supports multiple partitionings. In that case this method is equivalent to: 

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

getDocumentPartitioner

public IDocumentPartitioner getDocumentPartitioner()
Returns this document's partitioner.

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

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

getLineLength

public int getLineLength(int line)
                  throws BadLocationException
Returns the length of the given line including the line's delimiter.

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.

getLineOffset

public int getLineOffset(int line)
                  throws BadLocationException
Determines the offset of the first character of the given line.

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.

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.

getNumberOfLines

public int getNumberOfLines()
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.

computeNumberOfLines

public int computeNumberOfLines(java.lang.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().

getLegalLineDelimiters

public java.lang.String[] getLegalLineDelimiters()
Returns the document's legal line delimiters.

getLineDelimiter

public java.lang.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.

search

public int search(int startOffset,
                  java.lang.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.

Overview  Package   Class  Use  Deprecated  Index 
Home >> All >> org >> eclipse >> jface >> [ text overview ]  PREV CLASS  NEXT CLASS
SUMMARY: JavaDoc of org.eclipse.jface.text.IDocument JAVADOC | Sourc code of org.eclipse.jface.text.IDocument SOURCE | Download org.eclipse.jface.text.IDocument DOWNLOAD | NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD