SectionCollection
Inheritance: java.lang.Object, com.aspose.words.NodeCollection
public class SectionCollection extends NodeCollection
A collection of Section objects in the document.
To learn more, visit the Working with Sections documentation article.
Remarks:
A Microsoft Word document can contain multiple sections. To create a section in a Microsoft Word, select the Insert/Break command and select a break type. The break specifies whether section starts on a new page or on the same page.
Programmatically inserting and removing sections can be used to customize documents produced during mail merge. If a document needs to have different content or parts of the content depending on some criteria, then you can create a “master” document that contains multiple sections and delete some of the sections before or after mail merge.
Examples:
Shows how to add and remove sections in a document.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.write("Section 1");
builder.insertBreak(BreakType.SECTION_BREAK_NEW_PAGE);
builder.write("Section 2");
Assert.assertEquals("Section 1\fSection 2", doc.getText().trim());
// Delete the first section from the document.
doc.getSections().removeAt(0);
Assert.assertEquals("Section 2", doc.getText().trim());
// Append a copy of what is now the first section to the end of the document.
int lastSectionIdx = doc.getSections().getCount() - 1;
Section newSection = doc.getSections().get(lastSectionIdx).deepClone();
doc.getSections().add(newSection);
Assert.assertEquals("Section 2\fSection 2", doc.getText().trim());
Methods
| Method | Description |
|---|---|
| add(Node node) | Adds a node to the end of the collection. |
| clear() | Removes all nodes from this collection and from the document. |
| contains(Node node) | Determines whether a node is in the collection. |
| get(int index) | Retrieves a section at the given index. |
| getContainer() | |
| getCount() | Gets the number of nodes in the collection. |
| getCurrentNode() | |
| getNextMatchingNode(Node curNode) | |
| indexOf(Node node) | Returns the zero-based index of the specified node. |
| insert(int index, Node node) | Inserts a node into the collection at the specified index. |
| iterator() | Provides a simple “foreach” style iteration over the collection of nodes. |
| remove(Node node) | Removes the node from the collection and from the document. |
| removeAt(int index) | Removes the node at the specified index from the collection and from the document. |
| toArray() | Copies all sections from the collection to a new array of sections. |
add(Node node)
public void add(Node node)
Adds a node to the end of the collection.
Parameters:
| Parameter | Type | Description |
|---|---|---|
| node | Node | The node to be added to the end of the collection. |
clear()
public void clear()
Removes all nodes from this collection and from the document.
Examples:
Shows how to remove all sections from a document.
Document doc = new Document(getMyDir() + "Document.docx");
// This document has one section with a few child nodes containing and displaying all the document's contents.
Assert.assertEquals(doc.getSections().getCount(), 1);
Assert.assertEquals(doc.getSections().get(0).getChildNodes(NodeType.ANY, true).getCount(), 17);
Assert.assertEquals("Hello World!\r\rHello Word!\r\r\rHello World!", doc.getText().trim());
// Clear the collection of sections, which will remove all of the document's children.
doc.getSections().clear();
Assert.assertEquals(0, doc.getChildNodes(NodeType.ANY, true).getCount());
Assert.assertEquals("", doc.getText().trim());
contains(Node node)
public boolean contains(Node node)
Determines whether a node is in the collection.
Remarks:
This method performs a linear search; therefore, the average execution time is proportional to getCount().
Examples:
Shows how to work with a NodeCollection.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Add text to the document by inserting Runs using a DocumentBuilder.
builder.write("Run 1. ");
builder.write("Run 2. ");
// Every invocation of the "Write()" method creates a new Run,
// which then appears in the parent Paragraph's RunCollection.
RunCollection runs = doc.getFirstSection().getBody().getFirstParagraph().getRuns();
Assert.assertEquals(2, runs.getCount());
// We can also insert a node into the RunCollection manually.
Run newRun = new Run(doc, "Run 3. ");
runs.insert(3, newRun);
Assert.assertTrue(runs.contains(newRun));
Assert.assertEquals("Run 1. Run 2. Run 3.", doc.getText().trim());
// Access individual runs and remove them to remove their text from the document.
Run run = runs.get(1);
runs.remove(run);
Assert.assertEquals("Run 1. Run 3.", doc.getText().trim());
Assert.assertNotNull(run);
Assert.assertFalse(runs.contains(run));
Parameters:
| Parameter | Type | Description |
|---|---|---|
| node | Node | The node to locate. |
Returns: boolean - true if item is found in the collection; otherwise, false .
get(int index)
public Node get(int index)
Retrieves a section at the given index.
Remarks:
The index is zero-based.
Negative indexes are allowed and indicate access from the back of the collection. For example -1 means the last item, -2 means the second before last and so on.
If index is greater than or equal to the number of items in the list, this returns a null reference.
If index is negative and its absolute value is greater than the number of items in the list, this returns a null reference.
Examples:
Shows when to recalculate the page layout of the document.
Document doc = new Document(getMyDir() + "Rendering.docx");
// Saving a document to PDF, to an image, or printing for the first time will automatically
// cache the layout of the document within its pages.
doc.save(getArtifactsDir() + "Document.UpdatePageLayout.1.pdf");
// Modify the document in some way.
doc.getStyles().get("Normal").getFont().setSize(6.0);
doc.getSections().get(0).getPageSetup().setOrientation(Orientation.LANDSCAPE);
doc.getSections().get(0).getPageSetup().setMargins(Margins.MIRRORED);
// In the current version of Aspose.Words, modifying the document does not automatically rebuild
// the cached page layout. If we wish for the cached layout
// to stay up to date, we will need to update it manually.
doc.updatePageLayout();
doc.save(getArtifactsDir() + "Document.UpdatePageLayout.2.pdf");
Shows how to prepare a new section node for editing.
Document doc = new Document();
// A blank document comes with a section, which has a body, which in turn has a paragraph.
// We can add contents to this document by adding elements such as text runs, shapes, or tables to that paragraph.
Assert.assertEquals(NodeType.SECTION, doc.getChild(NodeType.ANY, 0, true).getNodeType());
Assert.assertEquals(NodeType.BODY, doc.getSections().get(0).getChild(NodeType.ANY, 0, true).getNodeType());
Assert.assertEquals(NodeType.PARAGRAPH, doc.getSections().get(0).getBody().getChild(NodeType.ANY, 0, true).getNodeType());
// If we add a new section like this, it will not have a body, or any other child nodes.
doc.getSections().add(new Section(doc));
Assert.assertEquals(0, doc.getSections().get(1).getChildNodes(NodeType.ANY, true).getCount());
// Run the "EnsureMinimum" method to add a body and a paragraph to this section to begin editing it.
doc.getLastSection().ensureMinimum();
Assert.assertEquals(NodeType.BODY, doc.getSections().get(1).getChild(NodeType.ANY, 0, true).getNodeType());
Assert.assertEquals(NodeType.PARAGRAPH, doc.getSections().get(1).getBody().getChild(NodeType.ANY, 0, true).getNodeType());
doc.getSections().get(0).getBody().getFirstParagraph().appendChild(new Run(doc, "Hello world!"));
Assert.assertEquals("Hello world!", doc.getText().trim());
Parameters:
| Parameter | Type | Description |
|---|---|---|
| index | int | An index into the list of sections. |
Returns: Node - The corresponding Section value.
getContainer()
public CompositeNode getContainer()
Returns: CompositeNode
getCount()
public int getCount()
Gets the number of nodes in the collection.
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;
}
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;
}
Returns: int - The number of nodes in the collection.
getCurrentNode()
public Node getCurrentNode()
Returns: Node
getNextMatchingNode(Node curNode)
public Node getNextMatchingNode(Node curNode)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| curNode | Node |
Returns: Node
indexOf(Node node)
public int indexOf(Node node)
Returns the zero-based index of the specified node.
Remarks:
This method performs a linear search; therefore, the average execution time is proportional to getCount().
Examples:
Shows how to get the index of a node in a collection.
Document doc = new Document(getMyDir() + "Tables.docx");
Table table = doc.getFirstSection().getBody().getTables().get(0);
NodeCollection allTables = doc.getChildNodes(NodeType.TABLE, true);
Assert.assertEquals(0, allTables.indexOf(table));
Row row = table.getRows().get(2);
Assert.assertEquals(2, table.indexOf(row));
Cell cell = row.getLastCell();
Assert.assertEquals(4, row.indexOf(cell));
Parameters:
| Parameter | Type | Description |
|---|---|---|
| node | Node | The node to locate. |
Returns: int - The zero-based index of the node within the collection, if found; otherwise, -1.
insert(int index, Node node)
public void insert(int index, Node node)
Inserts a node into the collection at the specified index.
Parameters:
| Parameter | Type | Description |
|---|---|---|
| index | int | The zero-based index of the node. Negative indexes are allowed and indicate access from the back of the list. For example -1 means the last node, -2 means the second before last and so on. |
| node | Node | The node to insert. |
iterator()
public Iterator iterator()
Provides a simple “foreach” style iteration over the collection of nodes.
Returns: java.util.Iterator - An Iterator.
remove(Node node)
public void remove(Node node)
Removes the node from the collection and from the document.
Examples:
Shows how to work with a NodeCollection.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Add text to the document by inserting Runs using a DocumentBuilder.
builder.write("Run 1. ");
builder.write("Run 2. ");
// Every invocation of the "Write()" method creates a new Run,
// which then appears in the parent Paragraph's RunCollection.
RunCollection runs = doc.getFirstSection().getBody().getFirstParagraph().getRuns();
Assert.assertEquals(2, runs.getCount());
// We can also insert a node into the RunCollection manually.
Run newRun = new Run(doc, "Run 3. ");
runs.insert(3, newRun);
Assert.assertTrue(runs.contains(newRun));
Assert.assertEquals("Run 1. Run 2. Run 3.", doc.getText().trim());
// Access individual runs and remove them to remove their text from the document.
Run run = runs.get(1);
runs.remove(run);
Assert.assertEquals("Run 1. Run 3.", doc.getText().trim());
Assert.assertNotNull(run);
Assert.assertFalse(runs.contains(run));
Parameters:
| Parameter | Type | Description |
|---|---|---|
| node | Node | The node to remove. |
removeAt(int index)
public void removeAt(int index)
Removes the node at the specified index from the collection and from the document.
Examples:
Shows how to add and remove sections in a document.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.write("Section 1");
builder.insertBreak(BreakType.SECTION_BREAK_NEW_PAGE);
builder.write("Section 2");
Assert.assertEquals("Section 1\fSection 2", doc.getText().trim());
// Delete the first section from the document.
doc.getSections().removeAt(0);
Assert.assertEquals("Section 2", doc.getText().trim());
// Append a copy of what is now the first section to the end of the document.
int lastSectionIdx = doc.getSections().getCount() - 1;
Section newSection = doc.getSections().get(lastSectionIdx).deepClone();
doc.getSections().add(newSection);
Assert.assertEquals("Section 2\fSection 2", doc.getText().trim());
Parameters:
| Parameter | Type | Description |
|---|---|---|
| index | int | The zero-based index of the node. Negative indexes are allowed and indicate access from the back of the list. For example -1 means the last node, -2 means the second before last and so on. |
toArray()
public Node[] toArray()
Copies all sections from the collection to a new array of sections.
Returns: com.aspose.words.Node[] - An array of sections.
