com.aspose.words
Class NodeCollection

java.lang.Object
    extended by com.aspose.words.NodeCollection
All Implemented Interfaces:
INodeCollection
Direct Known Subclasses:
BuildingBlockCollection, CellCollection, HeaderFooterCollection, ParagraphCollection, RowCollection, RunCollection, SectionCollection, TableCollection

public class NodeCollection 
extends java.lang.Object

Represents a collection of nodes of a specific type.

NodeCollection does not own the nodes it contains, rather, is just a selection of nodes of the specified type, but the nodes are stored in the tree under their respective parent nodes.

NodeCollection supports indexed access, iteration and provides add and remove methods.

The NodeCollection collection can be "live" or "snapshot". When the collection is live, changes to the children of the node object that it was created from are immediately reflected in the nodes returned by the NodeCollection properties and methods.

NodeCollection is returned by CompositeNode.getChildNodes(int, boolean, boolean) and also serves as a base class for typed node collections such as SectionCollection, ParagraphCollection etc.

NodeCollection can be "flat" and contain only immediate children of the node it was created from, or it can be "deep" and contain all descendant children.

Example:

Shows how to replace all textboxes with images.
Document doc = new Document(getMyDir() + "Shape.ReplaceTextboxesWithImages.doc");

// This gets a live collection of all shape nodes in the document.
NodeCollection shapeCollection = doc.getChildNodes(NodeType.SHAPE, true);

// Since we will be adding/removing nodes, it is better to copy all collection
// into a fixed size array, otherwise iterator will be invalidated.
Node[] shapes = shapeCollection.toArray();

for (Node shapeNodes : shapes)
{
    Shape shape = (Shape) shapeNodes;
    // Filter out all shapes that we don't need.
    if (shape.getShapeType() == ShapeType.TEXT_BOX)
    {
        // Create a new shape that will replace the existing shape.
        Shape image = new Shape(doc, ShapeType.IMAGE);

        // Load the image into the new shape.
        image.getImageData().setImage(getMyDir() + "Hammer.wmf");

        // Make new shape's position to match the old shape.
        image.setLeft(shape.getLeft());
        image.setTop(shape.getTop());
        image.setWidth(shape.getWidth());
        image.setHeight(shape.getHeight());
        image.setRelativeHorizontalPosition(shape.getRelativeHorizontalPosition());
        image.setRelativeVerticalPosition(shape.getRelativeVerticalPosition());
        image.setHorizontalAlignment(shape.getHorizontalAlignment());
        image.setVerticalAlignment(shape.getVerticalAlignment());
        image.setWrapType(shape.getWrapType());
        image.setWrapSide(shape.getWrapSide());

        // Insert new shape after the old shape and remove the old shape.
        shape.getParentNode().insertAfter(image, shape);
        shape.remove();
    }
}

doc.save(getMyDir() + "Shape.ReplaceTextboxesWithImages Out.doc");

Property Getters/Setters Summary
intgetCount()
           Gets the number of nodes in the collection.
Nodeget(int index)
           Retrieves a node at the given index.
 
Method Summary
voidadd(Node node)
           Adds a node to the end of the collection.
voidclear()
           Removes all nodes from this collection and from the document.
booleancontains(Node node)
           Determines whether a node is in the collection.
intindexOf(Node node)
           Returns the zero-based index of the specified node.
voidinsert(int index, Node node)
           Inserts a node into the collection at the specified index.
java.util.Iteratoriterator()
           Provides a simple "foreach" style iteration over the collection of nodes.
voidremove(Node node)
           Removes the node from the collection and from the document.
voidremoveAt(int index)
           Removes the node at the specified index from the collection and from the document.
Aspose.Words.Node[]toArray()
           Copies all nodes from the collection to a new array of nodes.
 

Property Getters/Setters Detail

getCount

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());
    }
}

get

public Node get(int index)
Retrieves a node 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 of nodes.

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());
    }
}

Method Detail

add

public void add(Node node)
        throws java.lang.Exception
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:

Creates a footer using the document object model and inserts it into a section.
Document doc = new Document();

HeaderFooter footer = new HeaderFooter(doc, HeaderFooterType.FOOTER_PRIMARY);
doc.getFirstSection().getHeadersFooters().add(footer);

Paragraph para = new Paragraph(doc);
footer.getParagraphs().add(para);

Run run = new Run(doc, "TEST FOOTER");
para.getRuns().add(run);

doc.save(getMyDir() + "HeaderFooter.CreateFooter Out.doc");

insert

public void insert(int index, Node node)
           throws java.lang.Exception
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.

remove

public void remove(Node node)
           throws java.lang.Exception
Removes the node from the collection and from the document.
Parameters:
node - The node to remove.

removeAt

public void removeAt(int index)
             throws java.lang.Exception
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.

clear

public void clear()
          throws java.lang.Exception
Removes all nodes from this collection and from the document.

contains

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.

indexOf

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.

toArray

public Aspose.Words.Node[] toArray()
Copies all nodes from the collection to a new array of nodes.

You should not be adding/removing nodes while iterating over a collection of nodes because it invalidates the iterator and requires refreshes for live collections.

To be able to add/remove nodes during iteration, use this method to copy nodes into a fixed-size array and then iterate over the array.

Returns:
An array of nodes.

Example:

Shows how to replace all textboxes with images.
Document doc = new Document(getMyDir() + "Shape.ReplaceTextboxesWithImages.doc");

// This gets a live collection of all shape nodes in the document.
NodeCollection shapeCollection = doc.getChildNodes(NodeType.SHAPE, true);

// Since we will be adding/removing nodes, it is better to copy all collection
// into a fixed size array, otherwise iterator will be invalidated.
Node[] shapes = shapeCollection.toArray();

for (Node shapeNodes : shapes)
{
    Shape shape = (Shape) shapeNodes;
    // Filter out all shapes that we don't need.
    if (shape.getShapeType() == ShapeType.TEXT_BOX)
    {
        // Create a new shape that will replace the existing shape.
        Shape image = new Shape(doc, ShapeType.IMAGE);

        // Load the image into the new shape.
        image.getImageData().setImage(getMyDir() + "Hammer.wmf");

        // Make new shape's position to match the old shape.
        image.setLeft(shape.getLeft());
        image.setTop(shape.getTop());
        image.setWidth(shape.getWidth());
        image.setHeight(shape.getHeight());
        image.setRelativeHorizontalPosition(shape.getRelativeHorizontalPosition());
        image.setRelativeVerticalPosition(shape.getRelativeVerticalPosition());
        image.setHorizontalAlignment(shape.getHorizontalAlignment());
        image.setVerticalAlignment(shape.getVerticalAlignment());
        image.setWrapType(shape.getWrapType());
        image.setWrapSide(shape.getWrapSide());

        // Insert new shape after the old shape and remove the old shape.
        shape.getParentNode().insertAfter(image, shape);
        shape.remove();
    }
}

doc.save(getMyDir() + "Shape.ReplaceTextboxesWithImages Out.doc");

iterator

public java.util.Iterator iterator()
Provides a simple "foreach" style iteration over the collection of nodes.
Returns:
Iterator<Node>.

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