public class MultiChangeBuilder<PS,SEG,S>
extends java.lang.Object
Replacement
s that are used to update an
EditableStyledDocument
in one call via commit()
. Note: this builder
cannot be reused and a new one must be created for each multi-change.
Let's say that a document has the text |(|t|e|x|t||)|
where each |
represents a position
in-between the characters of the text . If one wants to remove the opening
and closing parenthesis in two update calls, they would write:
// Text: |(|t|e|x|t|)|
// Position: 0 1 2 3 4 5 6
area.deleteText(0, 1); // delete the first parenthesis
// now the second parenthesis is positioned in a different spot than before
// Text: |t|e|x|t|)|
// Position: 0 1 2 3 4 5
area.deleteText(4, 5); // delete the second parenthesis
MultiChangeBuilder
can do the same thing in one call and works by applying earlier changes before
later ones. However, this creates a problem. Later changes' start and end positions must be updated to still
point to the correct spot in the text. Wouldn't it be easier to be able to define both changes in the original
coordinate system of the document before any changes were applied? Returning to the previous example,
wouldn't it be better if one could write:
// Text: |(|t|e|x|t|)|
// Position: 0 1 2 3 4 5 6
// start multi change
area.deleteText(0, 1); // delete the 1st parenthesis
area.deleteText(5, 6); // delete the 2nd parenthesis
// end multi change
Fortunately, that is already handled for you. Such changes are known as "relative" changes: their start and end positions are updated to point to where they should point once all the earlier changes before them have been applied. To execute the same code as before, we would write:
area.createMultiChange()
// deletes the 1st parenthesis
.deleteText(0, 1)
// internally updates this to delete(4, 5), so that it deletes the 2nd parenthesis
.deleteText(5, 6)
// executes the call and updates the document
.commit();
However, a developer may sometimes want an "absolute" change: their start and end positions are exactly what the developer specifies regardless of how changes before them modify the underlying document. For example, the following code would still delete both parenthesis:
area.createMultiChange()
.deleteText(0, 1) // deletes the 1st parenthesis
.deleteTextAbsolutely(4, 5) // deletes the 2nd parenthesis
.commit();
Thus, absolute changes (e.g. replaceAbsolutely(int, int, StyledDocument)
) are all the methods
which have "absolute" as a suffix and relative changes (e.g. replace(int, int, StyledDocument)
)
do not. To make things easier for the developer, the methods declared here are similar to those declared
in EditActions
, minus a few (e.g. EditActions.append(StyledDocument)
).
GenericStyledArea.replace(int, int, StyledDocument)
call.
// This code...
area.createMultiChange(4)
.replaceText(0, 1, "a")
.replaceTextAbsolutely(0, 1, "b")
.replaceTextAbsolutely(0, 1, "c")
.replaceTextAbsolutely(0, 1, "d")
.commit();
// ...could be optimized to...
area.createMultiChange(2)
.replaceText(0, 1, "a")
// .replaceTextAbsolutely(0, 1, "b") // superseded by next change
// .replaceTextAbsolutely(0, 1, "c") // superseded by next change
.replaceTextAbsolutely(0, 1, "d")
.commit();
// ...as it would reduce the number of updates by two and not create all the other objects
// associated with an update (e.g. RichTextChange, PlainTextChange, etc.).
Modifier and Type | Method | Description |
---|---|---|
void |
commit() |
Applies all the changes stored in this object to the underlying document of the area.
|
MultiChangeBuilder<PS,SEG,S> |
deleteText(int start,
int end) |
Removes a range of text.
|
MultiChangeBuilder<PS,SEG,S> |
deleteText(int startParagraph,
int startColumn,
int endParagraph,
int endColumn) |
Removes a range of text.
|
MultiChangeBuilder<PS,SEG,S> |
deleteText(javafx.scene.control.IndexRange range) |
Removes a range of text.
|
MultiChangeBuilder<PS,SEG,S> |
deleteTextAbsolutely(int start,
int end) |
Removes a range of text.
|
MultiChangeBuilder<PS,SEG,S> |
deleteTextAbsolutely(int startParagraph,
int startColumn,
int endParagraph,
int endColumn) |
Removes a range of text.
|
MultiChangeBuilder<PS,SEG,S> |
deleteTextAbsolutely(javafx.scene.control.IndexRange range) |
Removes a range of text.
|
MultiChangeBuilder<PS,SEG,S> |
insert(int paragraphIndex,
int columnPosition,
StyledDocument<PS,SEG,S> document) |
Inserts the given rich-text content at the position returned from
getAbsolutePosition(paragraphIndex, columnPosition) . |
MultiChangeBuilder<PS,SEG,S> |
insert(int position,
StyledDocument<PS,SEG,S> document) |
Inserts the given rich-text content at the given position.
|
MultiChangeBuilder<PS,SEG,S> |
insertAbsolutely(int paragraphIndex,
int columnPosition,
StyledDocument<PS,SEG,S> document) |
Inserts the given rich-text content at the position returned from
getAbsolutePosition(paragraphIndex, columnPosition) . |
MultiChangeBuilder<PS,SEG,S> |
insertAbsolutely(int position,
StyledDocument<PS,SEG,S> document) |
Inserts the given rich-text content at the given position.
|
MultiChangeBuilder<PS,SEG,S> |
insertText(int paragraphIndex,
int columnPosition,
java.lang.String text) |
Inserts the given text at the position returned from
getAbsolutePosition(paragraphIndex, columnPosition) . |
MultiChangeBuilder<PS,SEG,S> |
insertText(int position,
java.lang.String text) |
Inserts the given text at the given position.
|
MultiChangeBuilder<PS,SEG,S> |
insertTextAbsolutely(int paragraphIndex,
int columnPosition,
java.lang.String text) |
Inserts the given text at the position returned from
getAbsolutePosition(paragraphIndex, columnPosition) . |
MultiChangeBuilder<PS,SEG,S> |
insertTextAbsolutely(int position,
java.lang.String text) |
Inserts the given text at the given position.
|
MultiChangeBuilder<PS,SEG,S> |
replace(int start,
int end,
StyledDocument<PS,SEG,S> replacement) |
Replaces a range of characters with the given rich-text document.
|
MultiChangeBuilder<PS,SEG,S> |
replaceAbsolutely(int start,
int end,
StyledDocument<PS,SEG,S> replacement) |
Replaces a range of characters with the given rich-text document.
|
MultiChangeBuilder<PS,SEG,S> |
replaceText(int start,
int end,
java.lang.String text) |
Replaces a range of characters with the given text.
|
MultiChangeBuilder<PS,SEG,S> |
replaceTextAbsolutely(int start,
int end,
java.lang.String text) |
Replaces a range of characters with the given text.
|
public MultiChangeBuilder<PS,SEG,S> insertText(int position, java.lang.String text)
position
- The position to insert the text.text
- The text to insert.public MultiChangeBuilder<PS,SEG,S> insertTextAbsolutely(int position, java.lang.String text)
position
- The position to insert the text.text
- The text to insert.public MultiChangeBuilder<PS,SEG,S> insertText(int paragraphIndex, int columnPosition, java.lang.String text)
getAbsolutePosition(paragraphIndex, columnPosition)
.
Caution: see StyledDocument.getAbsolutePosition(int, int)
to know how the column index argument
can affect the returned position.
text
- The text to insertpublic MultiChangeBuilder<PS,SEG,S> insertTextAbsolutely(int paragraphIndex, int columnPosition, java.lang.String text)
getAbsolutePosition(paragraphIndex, columnPosition)
.
Caution: see StyledDocument.getAbsolutePosition(int, int)
to know how the column index argument
can affect the returned position.
text
- The text to insertpublic MultiChangeBuilder<PS,SEG,S> insert(int position, StyledDocument<PS,SEG,S> document)
position
- The position to insert the text.document
- The rich-text content to insert.public MultiChangeBuilder<PS,SEG,S> insertAbsolutely(int position, StyledDocument<PS,SEG,S> document)
position
- The position to insert the text.document
- The rich-text content to insert.public MultiChangeBuilder<PS,SEG,S> insert(int paragraphIndex, int columnPosition, StyledDocument<PS,SEG,S> document)
getAbsolutePosition(paragraphIndex, columnPosition)
.
Caution: see StyledDocument.getAbsolutePosition(int, int)
to know how the column index argument
can affect the returned position.
document
- The rich-text content to insert.public MultiChangeBuilder<PS,SEG,S> insertAbsolutely(int paragraphIndex, int columnPosition, StyledDocument<PS,SEG,S> document)
getAbsolutePosition(paragraphIndex, columnPosition)
.
Caution: see StyledDocument.getAbsolutePosition(int, int)
to know how the column index argument
can affect the returned position.
document
- The rich-text content to insert.public MultiChangeBuilder<PS,SEG,S> deleteText(javafx.scene.control.IndexRange range)
range
- The range of text to delete. It must not be null. Its start and end values specify the start
and end positions within the area.deleteText(int, int)
public MultiChangeBuilder<PS,SEG,S> deleteTextAbsolutely(javafx.scene.control.IndexRange range)
range
- The range of text to delete. It must not be null. Its start and end values specify the start
and end positions within the area.deleteText(int, int)
public MultiChangeBuilder<PS,SEG,S> deleteText(int start, int end)
0 <= start <= end <= getLength()
.start
- Start position of the range to removeend
- End position of the range to removepublic MultiChangeBuilder<PS,SEG,S> deleteTextAbsolutely(int start, int end)
0 <= start <= end <= getLength()
.start
- Start position of the range to removeend
- End position of the range to removepublic MultiChangeBuilder<PS,SEG,S> deleteText(int startParagraph, int startColumn, int endParagraph, int endColumn)
0 <= start <= end <= getLength()
where
start = getAbsolutePosition(startParagraph, startColumn);
and is inclusive, and
int end = getAbsolutePosition(endParagraph, endColumn);
and is exclusive.
Caution: see StyledDocument.getAbsolutePosition(int, int)
to know how the column index argument
can affect the returned position.
public MultiChangeBuilder<PS,SEG,S> deleteTextAbsolutely(int startParagraph, int startColumn, int endParagraph, int endColumn)
0 <= start <= end <= getLength()
where
start = getAbsolutePosition(startParagraph, startColumn);
and is inclusive, and
int end = getAbsolutePosition(endParagraph, endColumn);
and is exclusive.
Caution: see StyledDocument.getAbsolutePosition(int, int)
to know how the column index argument
can affect the returned position.
public MultiChangeBuilder<PS,SEG,S> replaceText(int start, int end, java.lang.String text)
0 <= start <= end <= getLength()
.start
- Start index of the range to replace, inclusive.end
- End index of the range to replace, exclusive.text
- The text to put in place of the deleted range.
It must not be null.public MultiChangeBuilder<PS,SEG,S> replaceTextAbsolutely(int start, int end, java.lang.String text)
0 <= start <= end <= getLength()
.start
- Start index of the range to replace, inclusive.end
- End index of the range to replace, exclusive.text
- The text to put in place of the deleted range.
It must not be null.public MultiChangeBuilder<PS,SEG,S> replace(int start, int end, StyledDocument<PS,SEG,S> replacement)
public MultiChangeBuilder<PS,SEG,S> replaceAbsolutely(int start, int end, StyledDocument<PS,SEG,S> replacement)
public final void commit()