Class TextEdit
- Direct Known Subclasses:
CopyingRangeMarker
,CopySourceEdit
,CopyTargetEdit
,DeleteEdit
,InsertEdit
,MoveSourceEdit
,MoveTargetEdit
,MultiTextEdit
,RangeMarker
,ReplaceEdit
,UndoEdit
IDocument
).
Text edits form a tree. Clients can navigate the tree upwards, from child to
parent, as well as downwards. Newly created edits are un-parented. New edits
are added to the tree by calling one of the add
methods on a parent
edit.
An edit tree is well formed in the following sense:
- a parent edit covers all its children
- children don't overlap
- an edit with length 0 can't have any children
Any manipulation of the tree that violates one of the above requirements results
in a MalformedTreeException
.
Insert edits are represented by an edit of length 0. If more than one insert edit exists at the same offset then the edits are executed in the order in which they have been added to a parent. The following code example:
IDocument document= new Document("org"); MultiTextEdit edit= new MultiTextEdit(); edit.addChild(new InsertEdit(0, "www.")); edit.addChild(new InsertEdit(0, "eclipse.")); edit.apply(document);
therefore results in string: "www.eclipse.org".
Text edits can be executed in a mode where the edit's region is updated to
reflect the edit's position in the changed document. Region updating is enabled
by default or can be requested by passing UPDATE_REGIONS
to the
apply(IDocument, int)
method. In the above example
the region of the InsertEdit(0, "eclipse.")
edit after executing
the root edit is [3, 8]
. If the region of an edit got deleted during
change execution the region is set to [-1, -1]
and the method isDeleted
returns true
.
MultiTextEdit
.- Since:
- 3.0
- Restriction:
- This class is not intended to be subclassed by clients.
-
Field Summary
Modifier and TypeFieldDescriptionstatic final int
Flags indicating that applying an edit tree to a document is supposed to create a corresponding undo edit.static final int
Flags indicating that neitherCREATE_UNDO
norUPDATE_REGIONS
is set.static final int
Flag indicating that the edit's region will be updated to reflect its position in the changed document. -
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionfinal void
accept
(TextEditVisitor visitor) Accepts the given visitor on a visit of the current edit.protected abstract void
accept0
(TextEditVisitor visitor) Accepts the given visitor on a type-specific visit of the current edit.protected final void
acceptChildren
(TextEditVisitor visitor) Accepts the given visitor on the edits children.final void
Adds the given editchild
to this edit.final void
addChildren
(TextEdit[] edits) Adds all edits inedits
to this edit.final UndoEdit
Applies the edit tree rooted by this edit to the given document.final UndoEdit
Applies the edit tree rooted by this edit to the given document.protected boolean
Returnstrue
if an edit with length zero can cover another edit.protected void
Hook method called when the document updating of a child edit has been completed.protected void
Hook method called when the region updating of a child edit has been completed.final TextEdit
copy()
Creates a deep copy of the edit tree rooted at this edit.boolean
Returnstrue
if the edit covers the given editother
.protected abstract TextEdit
doCopy()
Creates and returns a copy of this edit.final boolean
TheEdit
implementation of thisObject
method uses object identity (==).final TextEdit[]
Returns the edit's children.final int
Returns the size of the managed children.static IRegion
getCoverage
(TextEdit[] edits) Returns the text range spawned by the given array of text edits.final int
Returns the exclusive end position of this edit.final int
Returns the inclusive end position of this edit.int
Returns the length of the edit.int
Returns the offset of the edit.final TextEdit
Returns the edit's parent.final IRegion
Returns the range that this edit is manipulating.final TextEdit
getRoot()
Returns the root edit of the edit tree.final boolean
Returnstrue
if this edit has children.final int
hashCode()
TheEdit
implementation of thisObject
method calls usesObject#hashCode()
to compute its hash code.final boolean
Returns whether this edit has been deleted or not.final void
moveTree
(int delta) Move all offsets in the tree by the given delta.protected void
postProcessCopy
(TextEditCopier copier) This method is called on every edit of the copied tree to do some post-processing like connected an edit to a different edit in the tree.final TextEdit
removeChild
(int index) Removes the edit specified by the given index from the list of children.final boolean
removeChild
(TextEdit child) Removes the first occurrence of the given child from the list of children.final TextEdit[]
Removes all child edits from and returns them.toString()
-
Field Details
-
NONE
public static final int NONEFlags indicating that neitherCREATE_UNDO
norUPDATE_REGIONS
is set.- See Also:
-
CREATE_UNDO
public static final int CREATE_UNDOFlags indicating that applying an edit tree to a document is supposed to create a corresponding undo edit. If not specifiednull
is returned from methodapply
.- See Also:
-
UPDATE_REGIONS
public static final int UPDATE_REGIONSFlag indicating that the edit's region will be updated to reflect its position in the changed document. If not specified when applying an edit tree to a document the edit's region will be arbitrary. It is even not guaranteed that the tree is still well formed.- See Also:
-
-
Constructor Details
-
TextEdit
protected TextEdit(int offset, int length) Create a new text edit. Parent is initialized tonull
and the edit doesn't have any children.- Parameters:
offset
- the edit's offsetlength
- the edit's length
-
TextEdit
Copy constructor- Parameters:
source
- the source to copy form
-
-
Method Details
-
getRegion
Returns the range that this edit is manipulating. The returnedIRegion
contains the edit's offset and length at the point in time when this call is made. Any subsequent changes to the edit's offset and length aren't reflected in the returned region object.Creating a region for a deleted edit will result in an assertion failure.
- Returns:
- the manipulated region
-
getOffset
public int getOffset()Returns the offset of the edit. An offset is a 0-based character index. Returns-1
if the edit is marked as deleted.- Returns:
- the offset of the edit
-
getLength
public int getLength()Returns the length of the edit. Returns-1
if the edit is marked as deleted.- Returns:
- the length of the edit
-
getInclusiveEnd
public final int getInclusiveEnd()Returns the inclusive end position of this edit. The inclusive end position denotes the last character of the region manipulated by this edit. The returned value is the result of the following calculation:getOffset() + getLength() - 1;
- Returns:
- the inclusive end position
-
getExclusiveEnd
public final int getExclusiveEnd()Returns the exclusive end position of this edit. The exclusive end position denotes the next character of the region manipulated by this edit. The returned value is the result of the following calculation:getOffset() + getLength();
- Returns:
- the exclusive end position
-
isDeleted
public final boolean isDeleted()Returns whether this edit has been deleted or not.- Returns:
true
if the edit has been deleted; otherwisefalse
is returned.
-
moveTree
public final void moveTree(int delta) Move all offsets in the tree by the given delta. This node must be a root node. The resulting offsets must be greater or equal to zero.- Parameters:
delta
- the delta- Since:
- 3.1
-
covers
Returnstrue
if the edit covers the given editother
. It is up to the concrete text edit to decide if a edit of length zero can cover another edit.- Parameters:
other
- the other edit- Returns:
true
if the edit covers the other edit; otherwisefalse
is returned.
-
canZeroLengthCover
protected boolean canZeroLengthCover()Returnstrue
if an edit with length zero can cover another edit. Returnsfalse
otherwise.- Returns:
- whether an edit of length zero can cover another edit
-
getParent
Returns the edit's parent. The method returnsnull
if this edit hasn't been add to another edit.- Returns:
- the edit's parent
-
getRoot
Returns the root edit of the edit tree.- Returns:
- the root edit of the edit tree
- Since:
- 3.1
-
addChild
Adds the given editchild
to this edit.- Parameters:
child
- the child edit to add- Throws:
MalformedTreeException
- is thrown if the child edit can't be added to this edit. This is the case if the child overlaps with one of its siblings or if the child edit's region isn't fully covered by this edit.
-
addChildren
Adds all edits inedits
to this edit.- Parameters:
edits
- the text edits to add- Throws:
MalformedTreeException
- is thrown if one of the given edits can't be added to this edit.- See Also:
-
removeChild
Removes the edit specified by the given index from the list of children. Returns the child edit that was removed from the list of children. The parent of the returned edit is set tonull
.- Parameters:
index
- the index of the edit to remove- Returns:
- the removed edit
- Throws:
IndexOutOfBoundsException
- if the index is out of range
-
removeChild
Removes the first occurrence of the given child from the list of children.- Parameters:
child
- the child to be removed- Returns:
true
if the edit contained the given child; otherwisefalse
is returned
-
removeChildren
Removes all child edits from and returns them. The parent of the removed edits is set tonull
.- Returns:
- an array of the removed edits
-
hasChildren
public final boolean hasChildren()Returnstrue
if this edit has children. Otherwisefalse
is returned.- Returns:
true
if this edit has children; otherwisefalse
is returned
-
getChildren
Returns the edit's children. If the edit doesn't have any children an empty array is returned.- Returns:
- the edit's children
-
getChildrenSize
public final int getChildrenSize()Returns the size of the managed children.- Returns:
- the size of the children
-
getCoverage
Returns the text range spawned by the given array of text edits. The method requires that the given array contains at least one edit. If all edits passed are deleted the method returnsnull
.- Parameters:
edits
- an array of edits- Returns:
- the text range spawned by the given array of edits or
null
if all edits are marked as deleted
-
equals
TheEdit
implementation of thisObject
method uses object identity (==). -
hashCode
public final int hashCode()TheEdit
implementation of thisObject
method calls usesObject#hashCode()
to compute its hash code. -
toString
-
copy
Creates a deep copy of the edit tree rooted at this edit.- Returns:
- a deep copy of the edit tree
- See Also:
-
doCopy
Creates and returns a copy of this edit. The copy method should be implemented in a way so that the copy can executed without causing any harm to the original edit. Implementors of this method are responsible for creating deep or shallow copies of referenced object to fulfill this requirement.Implementers of this method should use the copy constructor
This method should not be called from outside the framework. Please useEdit#Edit
(Edit source) to initialize the edit part of the copy. Implementors aren't responsible to actually copy the children or to set the right parent.copy
to create a copy of a edit tree.- Returns:
- a copy of this edit.
- See Also:
-
postProcessCopy
This method is called on every edit of the copied tree to do some post-processing like connected an edit to a different edit in the tree.This default implementation does nothing
- Parameters:
copier
- the copier that manages a map between original and copied edit.- See Also:
-
accept
Accepts the given visitor on a visit of the current edit.- Parameters:
visitor
- the visitor object- Throws:
IllegalArgumentException
- if the visitor is null
-
accept0
Accepts the given visitor on a type-specific visit of the current edit. This method must be implemented in all concrete text edits.General template for implementation on each concrete TextEdit class:
boolean visitChildren= visitor.visit(this); if (visitChildren) { acceptChildren(visitor); }
accept
) takes care of invokingvisitor.preVisit(this)
andvisitor.postVisit(this)
.- Parameters:
visitor
- the visitor object
-
acceptChildren
Accepts the given visitor on the edits children.This method must be used by the concrete implementations of
accept
to traverse list-values properties; it encapsulates the proper handling of on-the-fly changes to the list.- Parameters:
visitor
- the visitor object
-
apply
public final UndoEdit apply(IDocument document, int style) throws MalformedTreeException, BadLocationException Applies the edit tree rooted by this edit to the given document. To check if the edit tree can be applied to the document either catchMalformedTreeException
or useTextEditProcessor
to execute an edit tree.- Parameters:
document
- the document to be manipulatedstyle
- flags controlling the execution of the edit tree. Valid flags are:CREATE_UNDO
andUPDATE_REGIONS
.- Returns:
- a undo edit, if
CREATE_UNDO
is specified. Otherwisenull
is returned. - Throws:
MalformedTreeException
- is thrown if the tree isn't in a valid state. This exception is thrown before any edit is executed. So the document is still in its original state.BadLocationException
- is thrown if one of the edits in the tree can't be executed. The state of the document is undefined if this exception is thrown.- See Also:
-
apply
Applies the edit tree rooted by this edit to the given document. This method is a convenience method forapply(document, CREATE_UNDO | UPDATE_REGIONS)
- Parameters:
document
- the document to which to apply this edit- Returns:
- a undo edit, if
CREATE_UNDO
is specified. Otherwisenull
is returned. - Throws:
MalformedTreeException
- is thrown if the tree isn't in a valid state. This exception is thrown before any edit is executed. So the document is still in its original state.BadLocationException
- is thrown if one of the edits in the tree can't be executed. The state of the document is undefined if this exception is thrown.- See Also:
-
childDocumentUpdated
protected void childDocumentUpdated()Hook method called when the document updating of a child edit has been completed. When a client callsapply(IDocument)
orapply(IDocument, int)
this method is calledgetChildrenSize()
times.May be overridden by subclasses of
MultiTextEdit
.- Since:
- 3.1
-
childRegionUpdated
protected void childRegionUpdated()Hook method called when the region updating of a child edit has been completed. When a client callsapply(IDocument)
this method is calledgetChildrenSize()
times. When callingapply(IDocument, int)
this method is calledgetChildrenSize()
times, when the style parameter contains theUPDATE_REGIONS
flag.May be overridden by subclasses of
MultiTextEdit
.- Since:
- 3.1
-