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
org.eclipse.jface.text.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
org.eclipse.jface.text.IDocumentExtension3introduced 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
org.eclipse.jface.text.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
- 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
org.eclipse.jface.text.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:
-
org.eclipse.jface.text.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
-
org.eclipse.jface.text.IDocumentExtension2 since version 2.1 introducing configuration
methods for post notification replaces and document change notification.
-
org.eclipse.jface.text.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.
-
org.eclipse.jface.text.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
.