EditableRangeStart
Inheritance: java.lang.Object, com.aspose.words.Node
public class EditableRangeStart extends Node
Represents a start of an editable range in a Word document.
To learn more, visit the Aspose.Words Document Object Model (DOM) documentation article.
Remarks:
A complete editable range in a Word document consists of a EditableRangeStart and a matching EditableRangeEnd with the same Id.
EditableRangeStart and EditableRangeEnd are just markers inside a document that specify where the editable range starts and ends.
Use the getEditableRange() class as a “facade” to work with an editable range as a single object.
Currently editable ranges are supported only at the inline-level, that is inside Paragraph, but editable range start and editable range end can be in different paragraphs.
Examples:
Shows how to limit the editing rights of editable ranges to a specific group/user.
public void visitor() throws Exception {
Document doc = new Document();
doc.protect(ProtectionType.READ_ONLY, "MyPassword");
DocumentBuilder builder = new DocumentBuilder(doc);
builder.writeln("Hello world! Since we have set the document's protection level to read-only," +
" we cannot edit this paragraph without the password.");
// When we write-protect documents, editable ranges allow us to pick specific areas that users may edit.
// There are two mutually exclusive ways to narrow down the list of allowed editors.
// 1 - Specify a user:
EditableRange editableRange = builder.startEditableRange().getEditableRange();
editableRange.setSingleUser("john.doe@myoffice.com");
builder.writeln(MessageFormat.format("This paragraph is inside the first editable range, can only be edited by {0}.", editableRange.getSingleUser()));
builder.endEditableRange();
Assert.assertEquals(EditorType.UNSPECIFIED, editableRange.getEditorGroup());
// 2 - Specify a group that allowed users are associated with:
editableRange = builder.startEditableRange().getEditableRange();
editableRange.setEditorGroup(EditorType.ADMINISTRATORS);
builder.writeln(MessageFormat.format("This paragraph is inside the first editable range, can only be edited by {0}.", editableRange.getEditorGroup()));
builder.endEditableRange();
Assert.assertEquals("", editableRange.getSingleUser());
builder.writeln("This paragraph is outside the editable range, and cannot be edited by anybody.");
// Print details and contents of every editable range in the document.
EditableRangePrinter editableRangePrinter = new EditableRangePrinter();
doc.accept(editableRangePrinter);
System.out.println(editableRangePrinter.toText());
}
///
/// Collects properties and contents of visited editable ranges in a string.
///
public static class EditableRangePrinter extends DocumentVisitor {
public EditableRangePrinter() {
mBuilder = new StringBuilder();
}
public String toText() {
return mBuilder.toString();
}
public void reset() {
mBuilder.setLength(0);
mInsideEditableRange = false;
}
///
/// Called when an EditableRangeStart node is encountered in the document.
///
public int visitEditableRangeStart(EditableRangeStart editableRangeStart) {
mBuilder.append(" -- Editable range found! -- ");
mBuilder.append("\tID:\t\t" + editableRangeStart.getId());
if (editableRangeStart.getEditableRange().getSingleUser().equals(""))
mBuilder.append("\tGroup:\t" + editableRangeStart.getEditableRange().getEditorGroup());
else
mBuilder.append("\tUser:\t" + editableRangeStart.getEditableRange().getSingleUser());
mBuilder.append("\tContents:");
mInsideEditableRange = true;
return VisitorAction.CONTINUE;
}
///
/// Called when an EditableRangeEnd node is encountered in the document.
///
public int visitEditableRangeEnd(final EditableRangeEnd editableRangeEnd) {
mBuilder.append(" -- End of editable range -- " + "\r\n");
mInsideEditableRange = false;
return VisitorAction.CONTINUE;
}
///
/// Called when a Run node is encountered in the document. This visitor only records runs that are inside editable ranges.
///
public int visitRun(final Run run) {
if (mInsideEditableRange) {
mBuilder.append("\t\"" + run.getText() + "\"" + "\r\n");
}
return VisitorAction.CONTINUE;
}
private boolean mInsideEditableRange;
private final StringBuilder mBuilder;
}
Methods
Method | Description |
---|---|
accept(DocumentVisitor visitor) | Accepts a visitor. |
dd() | |
deepClone(boolean isCloneChildren) | Creates a duplicate of the node. |
getAncestor(int ancestorType) | |
getAncestor(Class ancestorType) | Gets the first ancestor of the specified object type. |
getCustomNodeId() | Specifies custom node identifier. |
getDisplacedByCustomXml() | |
getDocument() | Gets the document to which this node belongs. |
getEditableRange() | Gets the facade object that encapsulates this editable range start and end. |
getId() | Specifies the identifier of the editable range. |
getIdInternal() | |
getNextSibling() | Gets the node immediately following this node. |
getNodeType() | Returns NodeType.EDITABLE_RANGE_START. |
getParentIdInternal() | |
getParentNode() | Gets the immediate parent of this node. |
getPreviousSibling() | Gets the node immediately preceding this node. |
getRange() | Returns a Range object that represents the portion of a document that is contained in this node. |
getText() | Gets the text of this node and of all its children. |
isComposite() | Returns true if this node can contain other nodes. |
nextPreOrder(Node rootNode) | Gets next node according to the pre-order tree traversal algorithm. |
nodeTypeToString(int nodeType) | |
previousPreOrder(Node rootNode) | Gets the previous node according to the pre-order tree traversal algorithm. |
remove() | Removes itself from the parent. |
setCustomNodeId(int value) | Specifies custom node identifier. |
setDisplacedByCustomXml(int value) | |
setId(int value) | Specifies the identifier of the editable range. |
setIdInternal(int value) | |
setParentIdInternal(int value) | |
toString() | |
toString(SaveOptions saveOptions) | Exports the content of the node into a string using the specified save options. |
toString(int saveFormat) |
accept(DocumentVisitor visitor)
public boolean accept(DocumentVisitor visitor)
Accepts a visitor.
Remarks:
Calls DocumentVisitor.visitEditableRangeStart(com.aspose.words.EditableRangeStart).
For more info see the Visitor design pattern.
Examples:
Shows how to limit the editing rights of editable ranges to a specific group/user.
public void visitor() throws Exception {
Document doc = new Document();
doc.protect(ProtectionType.READ_ONLY, "MyPassword");
DocumentBuilder builder = new DocumentBuilder(doc);
builder.writeln("Hello world! Since we have set the document's protection level to read-only," +
" we cannot edit this paragraph without the password.");
// When we write-protect documents, editable ranges allow us to pick specific areas that users may edit.
// There are two mutually exclusive ways to narrow down the list of allowed editors.
// 1 - Specify a user:
EditableRange editableRange = builder.startEditableRange().getEditableRange();
editableRange.setSingleUser("john.doe@myoffice.com");
builder.writeln(MessageFormat.format("This paragraph is inside the first editable range, can only be edited by {0}.", editableRange.getSingleUser()));
builder.endEditableRange();
Assert.assertEquals(EditorType.UNSPECIFIED, editableRange.getEditorGroup());
// 2 - Specify a group that allowed users are associated with:
editableRange = builder.startEditableRange().getEditableRange();
editableRange.setEditorGroup(EditorType.ADMINISTRATORS);
builder.writeln(MessageFormat.format("This paragraph is inside the first editable range, can only be edited by {0}.", editableRange.getEditorGroup()));
builder.endEditableRange();
Assert.assertEquals("", editableRange.getSingleUser());
builder.writeln("This paragraph is outside the editable range, and cannot be edited by anybody.");
// Print details and contents of every editable range in the document.
EditableRangePrinter editableRangePrinter = new EditableRangePrinter();
doc.accept(editableRangePrinter);
System.out.println(editableRangePrinter.toText());
}
///
/// Collects properties and contents of visited editable ranges in a string.
///
public static class EditableRangePrinter extends DocumentVisitor {
public EditableRangePrinter() {
mBuilder = new StringBuilder();
}
public String toText() {
return mBuilder.toString();
}
public void reset() {
mBuilder.setLength(0);
mInsideEditableRange = false;
}
///
/// Called when an EditableRangeStart node is encountered in the document.
///
public int visitEditableRangeStart(EditableRangeStart editableRangeStart) {
mBuilder.append(" -- Editable range found! -- ");
mBuilder.append("\tID:\t\t" + editableRangeStart.getId());
if (editableRangeStart.getEditableRange().getSingleUser().equals(""))
mBuilder.append("\tGroup:\t" + editableRangeStart.getEditableRange().getEditorGroup());
else
mBuilder.append("\tUser:\t" + editableRangeStart.getEditableRange().getSingleUser());
mBuilder.append("\tContents:");
mInsideEditableRange = true;
return VisitorAction.CONTINUE;
}
///
/// Called when an EditableRangeEnd node is encountered in the document.
///
public int visitEditableRangeEnd(final EditableRangeEnd editableRangeEnd) {
mBuilder.append(" -- End of editable range -- " + "\r\n");
mInsideEditableRange = false;
return VisitorAction.CONTINUE;
}
///
/// Called when a Run node is encountered in the document. This visitor only records runs that are inside editable ranges.
///
public int visitRun(final Run run) {
if (mInsideEditableRange) {
mBuilder.append("\t\"" + run.getText() + "\"" + "\r\n");
}
return VisitorAction.CONTINUE;
}
private boolean mInsideEditableRange;
private final StringBuilder mBuilder;
}
Parameters:
Parameter | Type | Description |
---|---|---|
visitor | DocumentVisitor | The visitor that will visit the node. |
Returns: boolean - false if the visitor requested the enumeration to stop.
dd()
public void dd()
deepClone(boolean isCloneChildren)
public Node deepClone(boolean isCloneChildren)
Creates a duplicate of the node.
Remarks:
This method serves as a copy constructor for nodes. The cloned node has no parent, but belongs to the same document as the original node.
This method always performs a deep copy of the node. The isCloneChildren parameter specifies whether to perform copy all child nodes as well.
Examples:
Shows how to clone a composite node.
Document doc = new Document();
Paragraph para = doc.getFirstSection().getBody().getFirstParagraph();
para.appendChild(new Run(doc, "Hello world!"));
// Below are two ways of cloning a composite node.
// 1 - Create a clone of a node, and create a clone of each of its child nodes as well.
Node cloneWithChildren = para.deepClone(true);
Assert.assertTrue(((CompositeNode) cloneWithChildren).hasChildNodes());
Assert.assertEquals("Hello world!", cloneWithChildren.getText().trim());
// 2 - Create a clone of a node just by itself without any children.
Node cloneWithoutChildren = para.deepClone(false);
Assert.assertFalse(((CompositeNode) cloneWithoutChildren).hasChildNodes());
Assert.assertEquals("", cloneWithoutChildren.getText().trim());
Parameters:
Parameter | Type | Description |
---|---|---|
isCloneChildren | boolean | True to recursively clone the subtree under the specified node; false to clone only the node itself. |
Returns: Node - The cloned node.
getAncestor(int ancestorType)
public CompositeNode getAncestor(int ancestorType)
Parameters:
Parameter | Type | Description |
---|---|---|
ancestorType | int |
Returns: CompositeNode
getAncestor(Class ancestorType)
public CompositeNode getAncestor(Class ancestorType)
Gets the first ancestor of the specified object type.
Remarks:
The ancestor type matches if it is equal to ancestorType or derived from ancestorType .
Examples:
Shows how to find out if a tables are nested.
public void calculateDepthOfNestedTables() throws Exception {
Document doc = new Document(getMyDir() + "Nested tables.docx");
NodeCollection tables = doc.getChildNodes(NodeType.TABLE, true);
for (int i = 0; i < tables.getCount(); i++) {
Table table = (Table) tables.get(i);
// Find out if any cells in the table have other tables as children.
int count = getChildTableCount(table);
System.out.print(MessageFormat.format("Table #{0} has {1} tables directly within its cells", i, count));
// Find out if the table is nested inside another table, and, if so, at what depth.
int tableDepth = getNestedDepthOfTable(table);
if (tableDepth > 0)
System.out.println(MessageFormat.format("Table #{0} is nested inside another table at depth of {1}", i, tableDepth));
else
System.out.println(MessageFormat.format("Table #{0} is a non nested table (is not a child of another table)", i));
}
}
// Calculates what level a table is nested inside other tables.
//
// Returns An integer containing the level the table is nested at.
// 0 = Table is not nested inside any other table
// 1 = Table is nested within one parent table
// 2 = Table is nested within two parent tables etc..
private static int getNestedDepthOfTable(final Table table) {
int depth = 0;
Node parent = table.getAncestor(table.getNodeType());
while (parent != null) {
depth++;
parent = parent.getAncestor(Table.class);
}
return depth;
}
// Determines if a table contains any immediate child table within its cells.
// Does not recursively traverse through those tables to check for further tables.
//
// Returns true if at least one child cell contains a table.
// Returns false if no cells in the table contains a table.
private static int getChildTableCount(final Table table) {
int childTableCount = 0;
for (Row row : table.getRows()) {
for (Cell cell : row.getCells()) {
TableCollection childTables = cell.getTables();
if (childTables.getCount() > 0) childTableCount++;
}
}
return childTableCount;
}
Parameters:
Parameter | Type | Description |
---|---|---|
ancestorType | java.lang.Class | The object type of the ancestor to retrieve. |
Returns: CompositeNode - The ancestor of the specified type or null if no ancestor of this type was found.
getCustomNodeId()
public int getCustomNodeId()
Specifies custom node identifier.
Remarks:
Default is zero.
This identifier can be set and used arbitrarily. For example, as a key to get external data.
Important note, specified value is not saved to an output file and exists only during the node lifetime.
Examples:
Shows how to traverse through a composite node’s collection of child nodes.
Document doc = new Document();
// Add two runs and one shape as child nodes to the first paragraph of this document.
Paragraph paragraph = (Paragraph) doc.getChild(NodeType.PARAGRAPH, 0, true);
paragraph.appendChild(new Run(doc, "Hello world! "));
Shape shape = new Shape(doc, ShapeType.RECTANGLE);
shape.setWidth(200.0);
shape.setHeight(200.0);
// Note that the 'CustomNodeId' is not saved to an output file and exists only during the node lifetime.
shape.setCustomNodeId(100);
shape.setWrapType(WrapType.INLINE);
paragraph.appendChild(shape);
paragraph.appendChild(new Run(doc, "Hello again!"));
// Iterate through the paragraph's collection of immediate children,
// and print any runs or shapes that we find within.
NodeCollection children = paragraph.getChildNodes(NodeType.ANY, false);
Assert.assertEquals(3, paragraph.getChildNodes(NodeType.ANY, false).getCount());
for (Node child : (Iterable) children)
switch (child.getNodeType()) {
case NodeType.RUN:
System.out.println("Run contents:");
System.out.println(MessageFormat.format("\t\"{0}\"", child.getText().trim()));
break;
case NodeType.SHAPE:
Shape childShape = (Shape)child;
System.out.println("Shape:");
System.out.println(MessageFormat.format("\t{0}, {1}x{2}", childShape.getShapeType(), childShape.getWidth(), childShape.getHeight()));
break;
}
Returns: int - The corresponding int value.
getDisplacedByCustomXml()
public int getDisplacedByCustomXml()
Returns: int
getDocument()
public DocumentBase getDocument()
Gets the document to which this node belongs.
Remarks:
The node always belongs to a document even if it has just been created and not yet added to the tree, or if it has been removed from the tree.
Examples:
Shows how to create a node and set its owning document.
Document doc = new Document();
Paragraph para = new Paragraph(doc);
para.appendChild(new Run(doc, "Hello world!"));
// We have not yet appended this paragraph as a child to any composite node.
Assert.assertNull(para.getParentNode());
// If a node is an appropriate child node type of another composite node,
// we can attach it as a child only if both nodes have the same owner document.
// The owner document is the document we passed to the node's constructor.
// We have not attached this paragraph to the document, so the document does not contain its text.
Assert.assertEquals(para.getDocument(), doc);
Assert.assertEquals("", doc.getText().trim());
// Since the document owns this paragraph, we can apply one of its styles to the paragraph's contents.
para.getParagraphFormat().setStyleName("Heading 1");
// Add this node to the document, and then verify its contents.
doc.getFirstSection().getBody().appendChild(para);
Assert.assertEquals(doc.getFirstSection().getBody(), para.getParentNode());
Assert.assertEquals("Hello world!", doc.getText().trim());
Returns: DocumentBase - The document to which this node belongs.
getEditableRange()
public EditableRange getEditableRange()
Gets the facade object that encapsulates this editable range start and end.
Examples:
Shows how to work with an editable range.
Document doc = new Document();
doc.protect(ProtectionType.READ_ONLY, "MyPassword");
DocumentBuilder builder = new DocumentBuilder(doc);
builder.writeln("Hello world! Since we have set the document's protection level to read-only," +
" we cannot edit this paragraph without the password.");
// Editable ranges allow us to leave parts of protected documents open for editing.
EditableRangeStart editableRangeStart = builder.startEditableRange();
builder.writeln("This paragraph is inside an editable range, and can be edited.");
EditableRangeEnd editableRangeEnd = builder.endEditableRange();
// A well-formed editable range has a start node, and end node.
// These nodes have matching IDs and encompass editable nodes.
EditableRange editableRange = editableRangeStart.getEditableRange();
Assert.assertEquals(editableRangeStart.getId(), editableRange.getId());
Assert.assertEquals(editableRangeEnd.getId(), editableRange.getId());
// Different parts of the editable range link to each other.
Assert.assertEquals(editableRangeStart.getId(), editableRange.getEditableRangeStart().getId());
Assert.assertEquals(editableRangeStart.getId(), editableRangeEnd.getEditableRangeStart().getId());
Assert.assertEquals(editableRange.getId(), editableRangeStart.getEditableRange().getId());
Assert.assertEquals(editableRangeEnd.getId(), editableRange.getEditableRangeEnd().getId());
// We can access the node types of each part like this. The editable range itself is not a node,
// but an entity which consists of a start, an end, and their enclosed contents.
Assert.assertEquals(NodeType.EDITABLE_RANGE_START, editableRangeStart.getNodeType());
Assert.assertEquals(NodeType.EDITABLE_RANGE_END, editableRangeEnd.getNodeType());
builder.writeln("This paragraph is outside the editable range, and cannot be edited.");
doc.save(getArtifactsDir() + "EditableRange.CreateAndRemove.docx");
// Remove an editable range. All the nodes that were inside the range will remain intact.
editableRange.remove();
Returns: EditableRange - The facade object that encapsulates this editable range start and end.
getId()
public int getId()
Specifies the identifier of the editable range.
Examples:
Shows how to work with an editable range.
Document doc = new Document();
doc.protect(ProtectionType.READ_ONLY, "MyPassword");
DocumentBuilder builder = new DocumentBuilder(doc);
builder.writeln("Hello world! Since we have set the document's protection level to read-only," +
" we cannot edit this paragraph without the password.");
// Editable ranges allow us to leave parts of protected documents open for editing.
EditableRangeStart editableRangeStart = builder.startEditableRange();
builder.writeln("This paragraph is inside an editable range, and can be edited.");
EditableRangeEnd editableRangeEnd = builder.endEditableRange();
// A well-formed editable range has a start node, and end node.
// These nodes have matching IDs and encompass editable nodes.
EditableRange editableRange = editableRangeStart.getEditableRange();
Assert.assertEquals(editableRangeStart.getId(), editableRange.getId());
Assert.assertEquals(editableRangeEnd.getId(), editableRange.getId());
// Different parts of the editable range link to each other.
Assert.assertEquals(editableRangeStart.getId(), editableRange.getEditableRangeStart().getId());
Assert.assertEquals(editableRangeStart.getId(), editableRangeEnd.getEditableRangeStart().getId());
Assert.assertEquals(editableRange.getId(), editableRangeStart.getEditableRange().getId());
Assert.assertEquals(editableRangeEnd.getId(), editableRange.getEditableRangeEnd().getId());
// We can access the node types of each part like this. The editable range itself is not a node,
// but an entity which consists of a start, an end, and their enclosed contents.
Assert.assertEquals(NodeType.EDITABLE_RANGE_START, editableRangeStart.getNodeType());
Assert.assertEquals(NodeType.EDITABLE_RANGE_END, editableRangeEnd.getNodeType());
builder.writeln("This paragraph is outside the editable range, and cannot be edited.");
doc.save(getArtifactsDir() + "EditableRange.CreateAndRemove.docx");
// Remove an editable range. All the nodes that were inside the range will remain intact.
editableRange.remove();
Returns: int - The corresponding int value.
getIdInternal()
public int getIdInternal()
Returns: int
getNextSibling()
public Node getNextSibling()
Gets the node immediately following this node.
Remarks:
If there is no next node, a null is returned.
Examples:
Shows how to use a node’s NextSibling property to enumerate through its immediate children.
Document doc = new Document(getMyDir() + "Paragraphs.docx");
for (Node node = doc.getFirstSection().getBody().getFirstChild(); node != null; node = node.getNextSibling()) {
System.out.println(Node.nodeTypeToString(node.getNodeType()));
}
Shows how to traverse a composite node’s tree of child nodes.
public void recurseChildren() throws Exception {
Document doc = new Document(getMyDir() + "Paragraphs.docx");
// Any node that can contain child nodes, such as the document itself, is composite.
Assert.assertTrue(doc.isComposite());
// Invoke the recursive function that will go through and print all the child nodes of a composite node.
traverseAllNodes(doc, 0);
}
///
/// Recursively traverses a node tree while printing the type of each node
/// with an indent depending on depth as well as the contents of all inline nodes.
///
public void traverseAllNodes(CompositeNode parentNode, int depth) {
for (Node childNode = parentNode.getFirstChild(); childNode != null; childNode = childNode.getNextSibling()) {
System.out.println(MessageFormat.format("{0}{1}", String.format(" ", depth), Node.nodeTypeToString(childNode.getNodeType())));
// Recurse into the node if it is a composite node. Otherwise, print its contents if it is an inline node.
if (childNode.isComposite()) {
System.out.println();
traverseAllNodes((CompositeNode) childNode, depth + 1);
} else if (childNode instanceof Inline) {
System.out.println(MessageFormat.format(" - \"{0}\"", childNode.getText().trim()));
} else {
System.out.println();
}
}
}
Returns: Node - The node immediately following this node.
getNodeType()
public int getNodeType()
Returns NodeType.EDITABLE_RANGE_START.
Examples:
Shows how to work with an editable range.
Document doc = new Document();
doc.protect(ProtectionType.READ_ONLY, "MyPassword");
DocumentBuilder builder = new DocumentBuilder(doc);
builder.writeln("Hello world! Since we have set the document's protection level to read-only," +
" we cannot edit this paragraph without the password.");
// Editable ranges allow us to leave parts of protected documents open for editing.
EditableRangeStart editableRangeStart = builder.startEditableRange();
builder.writeln("This paragraph is inside an editable range, and can be edited.");
EditableRangeEnd editableRangeEnd = builder.endEditableRange();
// A well-formed editable range has a start node, and end node.
// These nodes have matching IDs and encompass editable nodes.
EditableRange editableRange = editableRangeStart.getEditableRange();
Assert.assertEquals(editableRangeStart.getId(), editableRange.getId());
Assert.assertEquals(editableRangeEnd.getId(), editableRange.getId());
// Different parts of the editable range link to each other.
Assert.assertEquals(editableRangeStart.getId(), editableRange.getEditableRangeStart().getId());
Assert.assertEquals(editableRangeStart.getId(), editableRangeEnd.getEditableRangeStart().getId());
Assert.assertEquals(editableRange.getId(), editableRangeStart.getEditableRange().getId());
Assert.assertEquals(editableRangeEnd.getId(), editableRange.getEditableRangeEnd().getId());
// We can access the node types of each part like this. The editable range itself is not a node,
// but an entity which consists of a start, an end, and their enclosed contents.
Assert.assertEquals(NodeType.EDITABLE_RANGE_START, editableRangeStart.getNodeType());
Assert.assertEquals(NodeType.EDITABLE_RANGE_END, editableRangeEnd.getNodeType());
builder.writeln("This paragraph is outside the editable range, and cannot be edited.");
doc.save(getArtifactsDir() + "EditableRange.CreateAndRemove.docx");
// Remove an editable range. All the nodes that were inside the range will remain intact.
editableRange.remove();
Returns: int - NodeType.EDITABLE_RANGE_START. The returned value is one of NodeType constants.
getParentIdInternal()
public int getParentIdInternal()
Returns: int
getParentNode()
public CompositeNode getParentNode()
Gets the immediate parent of this node.
Remarks:
If a node has just been created and not yet added to the tree, or if it has been removed from the tree, the parent is null .
Examples:
Shows how to access a node’s parent node.
Document doc = new Document();
Paragraph para = doc.getFirstSection().getBody().getFirstParagraph();
// Append a child Run node to the document's first paragraph.
Run run = new Run(doc, "Hello world!");
para.appendChild(run);
// The paragraph is the parent node of the run node. We can trace this lineage
// all the way to the document node, which is the root of the document's node tree.
Assert.assertEquals(para, run.getParentNode());
Assert.assertEquals(doc.getFirstSection().getBody(), para.getParentNode());
Assert.assertEquals(doc.getFirstSection(), doc.getFirstSection().getBody().getParentNode());
Assert.assertEquals(doc, doc.getFirstSection().getParentNode());
Shows how to create a node and set its owning document.
Document doc = new Document();
Paragraph para = new Paragraph(doc);
para.appendChild(new Run(doc, "Hello world!"));
// We have not yet appended this paragraph as a child to any composite node.
Assert.assertNull(para.getParentNode());
// If a node is an appropriate child node type of another composite node,
// we can attach it as a child only if both nodes have the same owner document.
// The owner document is the document we passed to the node's constructor.
// We have not attached this paragraph to the document, so the document does not contain its text.
Assert.assertEquals(para.getDocument(), doc);
Assert.assertEquals("", doc.getText().trim());
// Since the document owns this paragraph, we can apply one of its styles to the paragraph's contents.
para.getParagraphFormat().setStyleName("Heading 1");
// Add this node to the document, and then verify its contents.
doc.getFirstSection().getBody().appendChild(para);
Assert.assertEquals(doc.getFirstSection().getBody(), para.getParentNode());
Assert.assertEquals("Hello world!", doc.getText().trim());
Returns: CompositeNode - The immediate parent of this node.
getPreviousSibling()
public Node getPreviousSibling()
Gets the node immediately preceding this node.
Remarks:
If there is no preceding node, a null is returned.
Examples:
Shows how to use of methods of Node and CompositeNode to remove a section before the last section in the document.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.writeln("Section 1 text.");
builder.insertBreak(BreakType.SECTION_BREAK_CONTINUOUS);
builder.writeln("Section 2 text.");
// Both sections are siblings of each other.
Section lastSection = (Section) doc.getLastChild();
Section firstSection = (Section) lastSection.getPreviousSibling();
// Remove a section based on its sibling relationship with another section.
if (lastSection.getPreviousSibling() != null)
doc.removeChild(firstSection);
// The section we removed was the first one, leaving the document with only the second.
Assert.assertEquals("Section 2 text.", doc.getText().trim());
Returns: Node - The node immediately preceding this node.
getRange()
public Range getRange()
Returns a Range object that represents the portion of a document that is contained in this node.
Examples:
Shows how to delete all the nodes from a range.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Add text to the first section in the document, and then add another section.
builder.write("Section 1. ");
builder.insertBreak(BreakType.SECTION_BREAK_CONTINUOUS);
builder.write("Section 2.");
Assert.assertEquals("Section 1. \fSection 2.", doc.getText().trim());
// Remove the first section entirely by removing all the nodes
// within its range, including the section itself.
doc.getSections().get(0).getRange().delete();
Assert.assertEquals(1, doc.getSections().getCount());
Assert.assertEquals("Section 2.", doc.getText().trim());
Returns: Range - A Range object that represents the portion of a document that is contained in this node.
getText()
public String getText()
Gets the text of this node and of all its children.
Remarks:
The returned string includes all control and special characters as described in ControlChar.
Examples:
Shows how to use control characters.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert paragraphs with text with DocumentBuilder.
builder.writeln("Hello world!");
builder.writeln("Hello again!");
// Converting the document to text form reveals that control characters
// represent some of the document's structural elements, such as page breaks.
Assert.assertEquals(MessageFormat.format("Hello world!{0}", ControlChar.CR) +
MessageFormat.format("Hello again!{0}", ControlChar.CR) +
ControlChar.PAGE_BREAK, doc.getText());
// When converting a document to string form,
// we can omit some of the control characters with the Trim method.
Assert.assertEquals(MessageFormat.format("Hello world!{0}", ControlChar.CR) +
"Hello again!", doc.getText().trim());
Shows how to construct an Aspose.Words document by hand.
Document doc = new Document();
// A blank document contains one section, one body and one paragraph.
// Call the "RemoveAllChildren" method to remove all those nodes,
// and end up with a document node with no children.
doc.removeAllChildren();
// This document now has no composite child nodes that we can add content to.
// If we wish to edit it, we will need to repopulate its node collection.
// First, create a new section, and then append it as a child to the root document node.
Section section = new Section(doc);
doc.appendChild(section);
// Set some page setup properties for the section.
section.getPageSetup().setSectionStart(SectionStart.NEW_PAGE);
section.getPageSetup().setPaperSize(PaperSize.LETTER);
// A section needs a body, which will contain and display all its contents
// on the page between the section's header and footer.
Body body = new Body(doc);
section.appendChild(body);
// Create a paragraph, set some formatting properties, and then append it as a child to the body.
Paragraph para = new Paragraph(doc);
para.getParagraphFormat().setStyleName("Heading 1");
para.getParagraphFormat().setAlignment(ParagraphAlignment.CENTER);
body.appendChild(para);
// Finally, add some content to do the document. Create a run,
// set its appearance and contents, and then append it as a child to the paragraph.
Run run = new Run(doc);
run.setText("Hello World!");
run.getFont().setColor(Color.RED);
para.appendChild(run);
Assert.assertEquals("Hello World!", doc.getText().trim());
doc.save(getArtifactsDir() + "Section.CreateManually.docx");
Returns: java.lang.String
isComposite()
public boolean isComposite()
Returns true if this node can contain other nodes. (181550,6)
Examples:
Shows how to traverse a composite node’s tree of child nodes.
public void recurseChildren() throws Exception {
Document doc = new Document(getMyDir() + "Paragraphs.docx");
// Any node that can contain child nodes, such as the document itself, is composite.
Assert.assertTrue(doc.isComposite());
// Invoke the recursive function that will go through and print all the child nodes of a composite node.
traverseAllNodes(doc, 0);
}
///
/// Recursively traverses a node tree while printing the type of each node
/// with an indent depending on depth as well as the contents of all inline nodes.
///
public void traverseAllNodes(CompositeNode parentNode, int depth) {
for (Node childNode = parentNode.getFirstChild(); childNode != null; childNode = childNode.getNextSibling()) {
System.out.println(MessageFormat.format("{0}{1}", String.format(" ", depth), Node.nodeTypeToString(childNode.getNodeType())));
// Recurse into the node if it is a composite node. Otherwise, print its contents if it is an inline node.
if (childNode.isComposite()) {
System.out.println();
traverseAllNodes((CompositeNode) childNode, depth + 1);
} else if (childNode instanceof Inline) {
System.out.println(MessageFormat.format(" - \"{0}\"", childNode.getText().trim()));
} else {
System.out.println();
}
}
}
Returns: boolean - true if this node can contain other nodes.
nextPreOrder(Node rootNode)
public Node nextPreOrder(Node rootNode)
Gets next node according to the pre-order tree traversal algorithm.
Examples:
Shows how to traverse the document’s node tree using the pre-order traversal algorithm, and delete any encountered shape with an image.
Document doc = new Document(getMyDir() + "Images.docx");
ArrayList shapes = (ArrayList) IterableUtils.toList(doc.getChildNodes(NodeType.SHAPE, true));
Assert.assertEquals(9, IterableUtils.countMatches(shapes, s -> {
try {
return s.hasImage();
} catch (Exception e) {
e.printStackTrace();
}
return false;
}));
Node curNode = doc;
while (curNode != null) {
Node nextNode = curNode.nextPreOrder(doc);
if (curNode.previousPreOrder(doc) != null && nextNode != null)
Assert.assertEquals(curNode, nextNode.previousPreOrder(doc));
if (curNode.getNodeType() == NodeType.SHAPE && ((Shape) curNode).hasImage())
curNode.remove();
curNode = nextNode;
}
shapes = (ArrayList) IterableUtils.toList(doc.getChildNodes(NodeType.SHAPE, true));
Assert.assertEquals(0, IterableUtils.countMatches(shapes, s -> {
try {
return s.hasImage();
} catch (Exception e) {
e.printStackTrace();
}
return false;
}));
Parameters:
Parameter | Type | Description |
---|---|---|
rootNode | Node | The top node (limit) of traversal. |
Returns: Node - Next node in pre-order order. Null if reached the rootNode .
nodeTypeToString(int nodeType)
public static String nodeTypeToString(int nodeType)
Parameters:
Parameter | Type | Description |
---|---|---|
nodeType | int |
Returns: java.lang.String
previousPreOrder(Node rootNode)
public Node previousPreOrder(Node rootNode)
Gets the previous node according to the pre-order tree traversal algorithm.
Examples:
Shows how to traverse the document’s node tree using the pre-order traversal algorithm, and delete any encountered shape with an image.
Document doc = new Document(getMyDir() + "Images.docx");
ArrayList shapes = (ArrayList) IterableUtils.toList(doc.getChildNodes(NodeType.SHAPE, true));
Assert.assertEquals(9, IterableUtils.countMatches(shapes, s -> {
try {
return s.hasImage();
} catch (Exception e) {
e.printStackTrace();
}
return false;
}));
Node curNode = doc;
while (curNode != null) {
Node nextNode = curNode.nextPreOrder(doc);
if (curNode.previousPreOrder(doc) != null && nextNode != null)
Assert.assertEquals(curNode, nextNode.previousPreOrder(doc));
if (curNode.getNodeType() == NodeType.SHAPE && ((Shape) curNode).hasImage())
curNode.remove();
curNode = nextNode;
}
shapes = (ArrayList) IterableUtils.toList(doc.getChildNodes(NodeType.SHAPE, true));
Assert.assertEquals(0, IterableUtils.countMatches(shapes, s -> {
try {
return s.hasImage();
} catch (Exception e) {
e.printStackTrace();
}
return false;
}));
Parameters:
Parameter | Type | Description |
---|---|---|
rootNode | Node | The top node (limit) of traversal. |
Returns: Node - Previous node in pre-order order. Null if reached the rootNode .
remove()
public void remove()
Removes itself from the parent.
Examples:
Shows how to remove all child nodes of a specific type from a composite node.
Document doc = new Document(getMyDir() + "Tables.docx");
Assert.assertEquals(2, doc.getChildNodes(NodeType.TABLE, true).getCount());
Node curNode = doc.getFirstSection().getBody().getFirstChild();
while (curNode != null) {
// Save the next sibling node as a variable in case we want to move to it after deleting this node.
Node nextNode = curNode.getNextSibling();
// A section body can contain Paragraph and Table nodes.
// If the node is a Table, remove it from the parent.
if (curNode.getNodeType() == NodeType.TABLE) {
curNode.remove();
}
curNode = nextNode;
}
Assert.assertEquals(0, doc.getChildNodes(NodeType.TABLE, true).getCount());
Shows how to delete all shapes with images from a document.
Document doc = new Document(getMyDir() + "Images.docx");
ArrayList shapes = (ArrayList) IterableUtils.toList(doc.getChildNodes(NodeType.SHAPE, true));
Assert.assertEquals(9, IterableUtils.countMatches(shapes, s -> {
try {
return s.hasImage();
} catch (Exception e) {
e.printStackTrace();
}
return false;
}));
for (Shape shape : shapes)
if (shape.hasImage())
shape.remove();
shapes = (ArrayList) IterableUtils.toList(doc.getChildNodes(NodeType.SHAPE, true));
Assert.assertEquals(0, IterableUtils.countMatches(shapes, s -> {
try {
return s.hasImage();
} catch (Exception e) {
e.printStackTrace();
}
return false;
}));
setCustomNodeId(int value)
public void setCustomNodeId(int value)
Specifies custom node identifier.
Remarks:
Default is zero.
This identifier can be set and used arbitrarily. For example, as a key to get external data.
Important note, specified value is not saved to an output file and exists only during the node lifetime.
Examples:
Shows how to traverse through a composite node’s collection of child nodes.
Document doc = new Document();
// Add two runs and one shape as child nodes to the first paragraph of this document.
Paragraph paragraph = (Paragraph) doc.getChild(NodeType.PARAGRAPH, 0, true);
paragraph.appendChild(new Run(doc, "Hello world! "));
Shape shape = new Shape(doc, ShapeType.RECTANGLE);
shape.setWidth(200.0);
shape.setHeight(200.0);
// Note that the 'CustomNodeId' is not saved to an output file and exists only during the node lifetime.
shape.setCustomNodeId(100);
shape.setWrapType(WrapType.INLINE);
paragraph.appendChild(shape);
paragraph.appendChild(new Run(doc, "Hello again!"));
// Iterate through the paragraph's collection of immediate children,
// and print any runs or shapes that we find within.
NodeCollection children = paragraph.getChildNodes(NodeType.ANY, false);
Assert.assertEquals(3, paragraph.getChildNodes(NodeType.ANY, false).getCount());
for (Node child : (Iterable) children)
switch (child.getNodeType()) {
case NodeType.RUN:
System.out.println("Run contents:");
System.out.println(MessageFormat.format("\t\"{0}\"", child.getText().trim()));
break;
case NodeType.SHAPE:
Shape childShape = (Shape)child;
System.out.println("Shape:");
System.out.println(MessageFormat.format("\t{0}, {1}x{2}", childShape.getShapeType(), childShape.getWidth(), childShape.getHeight()));
break;
}
Parameters:
Parameter | Type | Description |
---|---|---|
value | int | The corresponding int value. |
setDisplacedByCustomXml(int value)
public void setDisplacedByCustomXml(int value)
Parameters:
Parameter | Type | Description |
---|---|---|
value | int |
setId(int value)
public void setId(int value)
Specifies the identifier of the editable range.
Examples:
Shows how to work with an editable range.
Document doc = new Document();
doc.protect(ProtectionType.READ_ONLY, "MyPassword");
DocumentBuilder builder = new DocumentBuilder(doc);
builder.writeln("Hello world! Since we have set the document's protection level to read-only," +
" we cannot edit this paragraph without the password.");
// Editable ranges allow us to leave parts of protected documents open for editing.
EditableRangeStart editableRangeStart = builder.startEditableRange();
builder.writeln("This paragraph is inside an editable range, and can be edited.");
EditableRangeEnd editableRangeEnd = builder.endEditableRange();
// A well-formed editable range has a start node, and end node.
// These nodes have matching IDs and encompass editable nodes.
EditableRange editableRange = editableRangeStart.getEditableRange();
Assert.assertEquals(editableRangeStart.getId(), editableRange.getId());
Assert.assertEquals(editableRangeEnd.getId(), editableRange.getId());
// Different parts of the editable range link to each other.
Assert.assertEquals(editableRangeStart.getId(), editableRange.getEditableRangeStart().getId());
Assert.assertEquals(editableRangeStart.getId(), editableRangeEnd.getEditableRangeStart().getId());
Assert.assertEquals(editableRange.getId(), editableRangeStart.getEditableRange().getId());
Assert.assertEquals(editableRangeEnd.getId(), editableRange.getEditableRangeEnd().getId());
// We can access the node types of each part like this. The editable range itself is not a node,
// but an entity which consists of a start, an end, and their enclosed contents.
Assert.assertEquals(NodeType.EDITABLE_RANGE_START, editableRangeStart.getNodeType());
Assert.assertEquals(NodeType.EDITABLE_RANGE_END, editableRangeEnd.getNodeType());
builder.writeln("This paragraph is outside the editable range, and cannot be edited.");
doc.save(getArtifactsDir() + "EditableRange.CreateAndRemove.docx");
// Remove an editable range. All the nodes that were inside the range will remain intact.
editableRange.remove();
Parameters:
Parameter | Type | Description |
---|---|---|
value | int | The corresponding int value. |
setIdInternal(int value)
public void setIdInternal(int value)
Parameters:
Parameter | Type | Description |
---|---|---|
value | int |
setParentIdInternal(int value)
public void setParentIdInternal(int value)
Parameters:
Parameter | Type | Description |
---|---|---|
value | int |
toString()
public String toString()
Returns: java.lang.String
toString(SaveOptions saveOptions)
public String toString(SaveOptions saveOptions)
Exports the content of the node into a string using the specified save options.
Examples:
Exports the content of a node to String in HTML format.
Document doc = new Document(getMyDir() + "Document.docx");
Node node = doc.getLastSection().getBody().getLastParagraph();
// When we call the ToString method using the html SaveFormat overload,
// it converts the node's contents to their raw html representation.
Assert.assertEquals(" " +
"Hello World!" +
"", node.toString(SaveFormat.HTML));
// We can also modify the result of this conversion using a SaveOptions object.
HtmlSaveOptions saveOptions = new HtmlSaveOptions();
saveOptions.setExportRelativeFontSize(true);
Assert.assertEquals(" " +
"Hello World!" +
"", node.toString(saveOptions));
Parameters:
Parameter | Type | Description |
---|---|---|
saveOptions | SaveOptions | Specifies the options that control how the node is saved. |
Returns: java.lang.String - The content of the node in the specified format.
toString(int saveFormat)
public String toString(int saveFormat)
Parameters:
Parameter | Type | Description |
---|---|---|
saveFormat | int |
Returns: java.lang.String