com.aspose.words
Class RunCollection

java.lang.Object
  extended by NodeCollection
      extended by com.aspose.words.RunCollection
All Implemented Interfaces:
java.lang.Iterable

public class RunCollection 
extends NodeCollection

Provides typed access to a collection of Run nodes.

Example:

Shows how to process revision-related properties of Inline nodes.
Document doc = new Document(getMyDir() + "Inline.Revisions.docx");

// This document has 6 revisions
Assert.assertEquals(doc.getRevisions().getCount(), 6);

// The parent node of a revision is the run that the revision concerns, which is an Inline node
Run run = (Run) doc.getRevisions().get(0).getParentNode();

// Get the parent paragraph
Paragraph firstParagraph = run.getParentParagraph();
RunCollection runs = firstParagraph.getRuns();

Assert.assertEquals(runs.getCount(), 6);

// The text in the run at index #2 was typed after revisions were tracked, so it will count as an insert revision
// The font was changed, so it will also be a format revision
Assert.assertTrue(runs.get(2).isInsertRevision());
Assert.assertTrue(runs.get(2).isFormatRevision());

// If one node was moved from one place to another while changes were tracked,
// the node will be placed at the departure location as a "move to revision",
// and a "move from revision" node will be left behind at the origin, in case we want to reject changes
// Highlighting text and dragging it to another place with the mouse and cut-and-pasting (but not copy-pasting) both count as "move revisions"
// The node with the "IsMoveToRevision" flag is the arrival of the move operation, and the node with the "IsMoveFromRevision" flag is the departure point
Assert.assertTrue(runs.get(1).isMoveToRevision());
Assert.assertTrue(runs.get(4).isMoveFromRevision());

// If an Inline node gets deleted while changes are being tracked, it will leave behind a node with the IsDeleteRevision flag set to true until changes are accepted
Assert.assertTrue(runs.get(5).isDeleteRevision());

Property Getters/Setters Summary
intgetCount()→ inherited from NodeCollection
           Gets the number of nodes in the collection.
Runget(int index)
           Retrieves a Run at the given index.
 
Method Summary
voidadd(Node node)→ inherited from NodeCollection
           Adds a node to the end of the collection.
voidclear()→ inherited from NodeCollection
           Removes all nodes from this collection and from the document.
booleancontains(Node node)→ inherited from NodeCollection
           Determines whether a node is in the collection.
intindexOf(Node node)→ inherited from NodeCollection
           Returns the zero-based index of the specified node.
voidinsert(int index, Node node)→ inherited from NodeCollection
           Inserts a node into the collection at the specified index.
java.util.Iterator<Node>iterator()→ inherited from NodeCollection
          
voidremove(Node node)→ inherited from NodeCollection
           Removes the node from the collection and from the document.
voidremoveAt(int index)→ inherited from NodeCollection
           Removes the node at the specified index from the collection and from the document.
Run[]toArray()
           Copies all runs from the collection to a new array of runs.
 

Property Getters/Setters Detail

getCount

→ inherited from NodeCollection
public int getCount()
Gets the number of nodes in the collection.

Example:

Shows how to enumerate immediate children of a CompositeNode using indexed access.
NodeCollection children = paragraph.getChildNodes();
for (int i = 0; i < children.getCount(); i++) {
    Node child = children.get(i);

    // Paragraph may contain children of various types such as runs, shapes and so on.
    if (child.getNodeType() == NodeType.RUN) {
        // Say we found the node that we want, do something useful.
        Run run = (Run) child;
        System.out.println(run.getText());
    }
}

Example:

Shows how to find out if a table contains another table or if the table itself is nested inside another table.
public void calculateDepthOfNestedTables() throws Exception {
    Document doc = new Document(getMyDir() + "Table.NestedTables.doc");
    int tableIndex = 0;

    for (Table table : (Iterable<Table>) doc.getChildNodes(NodeType.TABLE, true)) {
        // First lets find if any cells in the table have tables themselves as children.
        int count = getChildTableCount(table);
        System.out.println(MessageFormat.format("Table #{0} has {1} tables directly within its cells", tableIndex, count));

        // Now let's try the other way around, lets try find if the table is nested inside another table and 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}", tableIndex, tableDepth));
        } else {
            System.out.println(MessageFormat.format("Table #{0} is a non nested table (is not a child of another table)", tableIndex));
        }

        tableIndex++;
    }
}

/**
 * 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;

    int type = table.getNodeType();
    // The parent of the table will be a Cell, instead attempt to find a grandparent that is of type Table
    Node parent = table.getAncestor(table.getNodeType());

    while (parent != null) {
        // Every time we find a table a level up we increase the depth counter and then try to find an
        // ancestor of type table from the parent.
        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 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 tableCount = 0;
    // Iterate through all child rows in the table
    for (Row row : table.getRows()) {
        // Iterate through all child cells in the row
        for (Cell cell : row.getCells()) {
            // Retrieve the collection of child tables of this cell
            TableCollection childTables = cell.getTables();

            // If this cell has a table as a child then return true
            if (childTables.getCount() > 0) tableCount++;
        }
    }

    // No cell contains a table
    return tableCount;
}

get

public Run get(int index)
Retrieves a Run at the given index.

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.

Parameters:
index - An index into the collection.

Example:

Shows how to process revision-related properties of Inline nodes.
Document doc = new Document(getMyDir() + "Inline.Revisions.docx");

// This document has 6 revisions
Assert.assertEquals(doc.getRevisions().getCount(), 6);

// The parent node of a revision is the run that the revision concerns, which is an Inline node
Run run = (Run) doc.getRevisions().get(0).getParentNode();

// Get the parent paragraph
Paragraph firstParagraph = run.getParentParagraph();
RunCollection runs = firstParagraph.getRuns();

Assert.assertEquals(runs.getCount(), 6);

// The text in the run at index #2 was typed after revisions were tracked, so it will count as an insert revision
// The font was changed, so it will also be a format revision
Assert.assertTrue(runs.get(2).isInsertRevision());
Assert.assertTrue(runs.get(2).isFormatRevision());

// If one node was moved from one place to another while changes were tracked,
// the node will be placed at the departure location as a "move to revision",
// and a "move from revision" node will be left behind at the origin, in case we want to reject changes
// Highlighting text and dragging it to another place with the mouse and cut-and-pasting (but not copy-pasting) both count as "move revisions"
// The node with the "IsMoveToRevision" flag is the arrival of the move operation, and the node with the "IsMoveFromRevision" flag is the departure point
Assert.assertTrue(runs.get(1).isMoveToRevision());
Assert.assertTrue(runs.get(4).isMoveFromRevision());

// If an Inline node gets deleted while changes are being tracked, it will leave behind a node with the IsDeleteRevision flag set to true until changes are accepted
Assert.assertTrue(runs.get(5).isDeleteRevision());

Method Detail

add

→ inherited from NodeCollection
public void add(Node node)
Adds a node to the end of the collection.

The node is inserted as a child into the node object from which the collection was created.

If the newChild is already in the tree, it is first removed.

If the node being inserted was created from another document, you should use DocumentBase.importNode(com.aspose.words.Node,boolean,int) to import the node to the current document. The imported node can then be inserted into the current document.

Parameters:
node - The node to be added to the end of the collection.

Example:

Shows how to add a section to the end of the document.
Document doc = new Document(getMyDir() + "Document.doc");
Section sectionToAdd = new Section(doc);
doc.getSections().add(sectionToAdd);

clear

→ inherited from NodeCollection
public void clear()
Removes all nodes from this collection and from the document.

Example:

Shows how to remove all sections from a document.
Document doc = new Document(getMyDir() + "Document.doc");
doc.getSections().clear();

contains

→ inherited from NodeCollection
public boolean contains(Node node)
Determines whether a node is in the collection.

This method performs a linear search; therefore, the average execution time is proportional to Count.

Parameters:
node - The node to locate.
Returns:
True if item is found in the collection; otherwise, false.

Example:

Shows how to work with a NodeCollection.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// The normal way to insert Runs into a document is to add text using a DocumentBuilder
builder.write("Run 1. ");
builder.write("Run 2. ");

// Every .Write() invocation creates a new Run, which is added to the parent Paragraph's RunCollection
RunCollection runs = doc.getFirstSection().getBody().getFirstParagraph().getRuns();
Assert.assertEquals(runs.getCount(), 2);

// We can insert a node into the RunCollection manually to achieve the same effect
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());

// Text can also be deleted from the document by accessing individual Runs via the RunCollection and editing or removing them
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));

indexOf

→ inherited from NodeCollection
public int indexOf(Node node)
Returns the zero-based index of the specified node.

This method performs a linear search; therefore, the average execution time is proportional to Count.

Parameters:
node - The node to locate.
Returns:
The zero-based index of the node within the collection, if found; otherwise, -1.

Example:

Retrieves the index of a table in the document.
NodeCollection allTables = doc.getChildNodes(NodeType.TABLE, true);
int tableIndex = allTables.indexOf(table);

insert

→ inherited from NodeCollection
public void insert(int index, Node node)
Inserts a node into the collection at the specified index.

The node is inserted as a child into the node object from which the collection was created.

If the index is equal to or greater than Count, the node is added at the end of the collection.

If the index is negative and its absolute value is greater than Count, the node is added at the end of the collection.

If the newChild is already in the tree, it is first removed.

If the node being inserted was created from another document, you should use DocumentBase.importNode(com.aspose.words.Node,boolean,int) to import the node to the current document. The imported node can then be inserted into the current document.

Parameters:
index - 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 - The node to insert.

Example:

Shows how to work with a NodeCollection.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// The normal way to insert Runs into a document is to add text using a DocumentBuilder
builder.write("Run 1. ");
builder.write("Run 2. ");

// Every .Write() invocation creates a new Run, which is added to the parent Paragraph's RunCollection
RunCollection runs = doc.getFirstSection().getBody().getFirstParagraph().getRuns();
Assert.assertEquals(runs.getCount(), 2);

// We can insert a node into the RunCollection manually to achieve the same effect
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());

// Text can also be deleted from the document by accessing individual Runs via the RunCollection and editing or removing them
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));

iterator

→ inherited from NodeCollection
public java.util.Iterator<Nodeiterator()

remove

→ inherited from NodeCollection
public void remove(Node node)
Removes the node from the collection and from the document.
Parameters:
node - The node to remove.

Example:

Shows how to work with a NodeCollection.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// The normal way to insert Runs into a document is to add text using a DocumentBuilder
builder.write("Run 1. ");
builder.write("Run 2. ");

// Every .Write() invocation creates a new Run, which is added to the parent Paragraph's RunCollection
RunCollection runs = doc.getFirstSection().getBody().getFirstParagraph().getRuns();
Assert.assertEquals(runs.getCount(), 2);

// We can insert a node into the RunCollection manually to achieve the same effect
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());

// Text can also be deleted from the document by accessing individual Runs via the RunCollection and editing or removing them
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));

removeAt

→ inherited from NodeCollection
public void removeAt(int index)
Removes the node at the specified index from the collection and from the document.
Parameters:
index - 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.

Example:

Shows how to add/remove sections in a document.
// Open the document.
Document doc = new Document(getMyDir() + "Section.AddRemove.doc");

// This shows what is in the document originally. The document has two sections.
System.out.println(doc.getText());

// Delete the first section from the document
doc.getSections().removeAt(0);

// Duplicate the last section and append the copy to the end of the document.
int lastSectionIdx = doc.getSections().getCount() - 1;
Section newSection = doc.getSections().get(lastSectionIdx).deepClone();
doc.getSections().add(newSection);

// Check what the document contains after we changed it.
System.out.println(doc.getText());

toArray

public Run[] toArray()
Copies all runs from the collection to a new array of runs.
Returns:
An array of runs.

Example:

Shows how to process revision-related properties of Inline nodes.
Document doc = new Document(getMyDir() + "Inline.Revisions.docx");

// This document has 6 revisions
Assert.assertEquals(doc.getRevisions().getCount(), 6);

// The parent node of a revision is the run that the revision concerns, which is an Inline node
Run run = (Run) doc.getRevisions().get(0).getParentNode();

// Get the parent paragraph
Paragraph firstParagraph = run.getParentParagraph();
RunCollection runs = firstParagraph.getRuns();

Assert.assertEquals(runs.getCount(), 6);

// The text in the run at index #2 was typed after revisions were tracked, so it will count as an insert revision
// The font was changed, so it will also be a format revision
Assert.assertTrue(runs.get(2).isInsertRevision());
Assert.assertTrue(runs.get(2).isFormatRevision());

// If one node was moved from one place to another while changes were tracked,
// the node will be placed at the departure location as a "move to revision",
// and a "move from revision" node will be left behind at the origin, in case we want to reject changes
// Highlighting text and dragging it to another place with the mouse and cut-and-pasting (but not copy-pasting) both count as "move revisions"
// The node with the "IsMoveToRevision" flag is the arrival of the move operation, and the node with the "IsMoveFromRevision" flag is the departure point
Assert.assertTrue(runs.get(1).isMoveToRevision());
Assert.assertTrue(runs.get(4).isMoveFromRevision());

// If an Inline node gets deleted while changes are being tracked, it will leave behind a node with the IsDeleteRevision flag set to true until changes are accepted
Assert.assertTrue(runs.get(5).isDeleteRevision());

See Also:
          Aspose.Words Documentation - the home page for the Aspose.Words Product Documentation.
          Aspose.Words Support Forum - our preferred method of support.