|
Eclipse Platform Release 3.1 |
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
An IDocument
represents text providing support for
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.
An IDocument
does not care about mixed line delimiters. Clients who
want to ensure a single line delimiter in their document should use the line
delimiter returned by TextUtilities.getDefaultLineDelimiter(IDocument)
.
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:
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. IDocumentExtension4
since version 3.1 introducing the
concept of rewrite sessions. A rewrite session is a sequence of document replace operations
that form a semantic unit. It also introduces a modification stamp and the ability to
set the initial line delimiter and to query the default line delimiter.
Clients may implement this interface and its extension interfaces or use the default
implementation provided by AbstractDocument
and Document
.
IDocumentExtension
,
IDocumentExtension2
,
IDocumentExtension3
,
IDocumentExtension4
,
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 |
public static final String DEFAULT_CATEGORY
public static final String DEFAULT_CONTENT_TYPE
Method Detail |
public char getChar(int offset) throws BadLocationException
offset
- a document offset
BadLocationException
- if the offset is invalid in this documentpublic int getLength()
public String get()
public String get(int offset, int length) throws BadLocationException
offset
- the document offsetlength
- the length of the specified range
BadLocationException
- if the range is invalid in this documentpublic void set(String text)
DocumentEvent
to all registered IDocumentListener
.
This method is a convenience method for replace(0, getLength(), text)
.
text
- the new content of the documentDocumentEvent
,
IDocumentListener
public void replace(int offset, int length, String text) throws BadLocationException
DocumentEvent
to all registered IDocumentListener
.
offset
- the document offsetlength
- the length of the specified rangetext
- the substitution text
BadLocationException
- if the offset is invalid in this documentDocumentEvent
,
IDocumentListener
public void addDocumentListener(IDocumentListener listener)
An IDocumentListener
may call back to this method
when being inside a document notification.
listener
- the listener to be registeredpublic void removeDocumentListener(IDocumentListener listener)
An IDocumentListener
may call back to this method
when being inside a document notification.
listener
- the listener to be removedpublic void addPrenotifiedDocumentListener(IDocumentListener documentAdapter)
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.
documentAdapter
- the listener to be added as pre-notified document listenerremovePrenotifiedDocumentListener(IDocumentListener)
public void removePrenotifiedDocumentListener(IDocumentListener documentAdapter)
This method is not for public use.
documentAdapter
- the listener to be removedaddPrenotifiedDocumentListener(IDocumentListener)
public void addPositionCategory(String category)
category
- the category to be addedpublic void removePositionCategory(String category) throws BadPositionCategoryException
category
- the category to be removed
BadPositionCategoryException
- if category is undefined in this documentpublic String[] getPositionCategories()
public boolean containsPositionCategory(String category)
category
- the category to check
true
if category is definedpublic void addPosition(Position position) throws BadLocationException
addPosition(DEFAULT_CATEGORY, position)
.
position
- the position to be added
BadLocationException
- if position describes an invalid range in this documentpublic void removePosition(Position position)
removePosition(DEFAULT_CATEGORY, position)
.
position
- the position to be removedpublic void addPosition(String category, Position position) throws BadLocationException, BadPositionCategoryException
category
- the category to which to addposition
- the position to be added
BadLocationException
- if position describes an invalid range in this document
BadPositionCategoryException
- if the category is undefined in this documentpublic void removePosition(String category, Position position) throws BadPositionCategoryException
category
- the category from which to deleteposition
- the position to be deleted
BadPositionCategoryException
- if category is undefined in this documentpublic Position[] getPositions(String category) throws BadPositionCategoryException
category
- the category
BadPositionCategoryException
- if category is undefined in this documentpublic boolean containsPosition(String category, int offset, int length)
category
- the category to checkoffset
- the offset of the position to findlength
- the length of the position to find
true
if position is foundpublic int computeIndexInCategory(String category, int offset) throws BadLocationException, BadPositionCategoryException
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.
category
- the category in which would be addedoffset
- the position offset to be considered
BadLocationException
- if offset is invalid in this document
BadPositionCategoryException
- if category is undefined in this documentpublic void addPositionUpdater(IPositionUpdater updater)
An IPositionUpdater
may call back to this method
when being inside a document notification.
updater
- the updater to be addedpublic void removePositionUpdater(IPositionUpdater updater)
An IPositionUpdater
may call back to this method
when being inside a document notification.
updater
- the updater to be removedpublic void insertPositionUpdater(IPositionUpdater updater, int index)
An IPositionUpdater
may call back to this method
when being inside a document notification.
updater
- the updater to be insertedindex
- the index in the document's updater listpublic IPositionUpdater[] getPositionUpdaters()
public String[] getLegalContentTypes()
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);
public String getContentType(int offset) throws BadLocationException
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);
offset
- the document offset
BadLocationException
- if offset is invalid in this documentpublic ITypedRegion getPartition(int offset) throws BadLocationException
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);
offset
- the document offset
BadLocationException
- if offset is invalid in this documentpublic ITypedRegion[] computePartitioning(int offset, int length) throws BadLocationException
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);
offset
- the document offset at which the range startslength
- the length of the document range
BadLocationException
- if the range is invalid in this documentpublic void addDocumentPartitioningListener(IDocumentPartitioningListener listener)
An IDocumentPartitioningListener
may call back to this method
when being inside a document notification.
listener
- the listener to be addedpublic void removeDocumentPartitioningListener(IDocumentPartitioningListener listener)
An IDocumentPartitioningListener
may call back to this method
when being inside a document notification.
listener
- the listener to be removedpublic void setDocumentPartitioner(IDocumentPartitioner partitioner)
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);
partitioner
- the document's new partitionerIDocumentPartitioningListener
public IDocumentPartitioner getDocumentPartitioner()
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);
public int getLineLength(int line) throws BadLocationException
line
- the line of interest
BadLocationException
- if the line number is invalid in this documentpublic int getLineOfOffset(int offset) throws BadLocationException
(offset == document length)
is a valid argument although there is no
corresponding character.
offset
- the document offset
BadLocationException
- if the offset is invalid in this documentpublic int getLineOffset(int line) throws BadLocationException
line
- the line of interest
BadLocationException
- if the line number is invalid in this documentpublic IRegion getLineInformation(int line) throws BadLocationException
line
- the line of interest
BadLocationException
- if the line number is invalid in this documentpublic IRegion getLineInformationOfOffset(int offset) throws BadLocationException
offset
- the offset whose line should be described
BadLocationException
- if offset is invalid in this documentpublic int getNumberOfLines()
public int getNumberOfLines(int offset, int length) throws BadLocationException
offset
- the offset of the specified text rangelength
- the length of the specified text range
BadLocationException
- if specified range is invalid in this trackerpublic int computeNumberOfLines(String text)
set(text); getNumberOfLines()
.
text
- the text whose number of lines should be computed
public String[] getLegalLineDelimiters()
public String getLineDelimiter(int line) throws BadLocationException
null
if the
line is not closed with a line delimiter.
line
- the line of interest
null
if line does not have a delimiter
BadLocationException
- if the line number is invalid in this documentpublic int search(int startOffset, String findString, boolean forwardSearch, boolean caseSensitive, boolean wholeWord) throws BadLocationException
FindReplaceDocumentAdapter
startOffset
- document offset at which search startsfindString
- the string to findforwardSearch
- the search directioncaseSensitive
- indicates whether lower and upper case should be distinguishedwholeWord
- indicates whether the findString should be limited by white spaces as
defined by Character.isWhiteSpace
BadLocationException
- if startOffset is an invalid document offset
|
Eclipse Platform Release 3.1 |
|||||||||||
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, 2005. All rights reserved.