Aspose::Words::NodeCollection Class Reference

Detailed Description

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 is "live", i.e. 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 GetChildNodes() 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.

Examples

Shows how to replace all textboxes with images.

auto doc = MakeObject<Document>(MyDir + u"Textboxes in drawing canvas.docx");
// This gets a live collection of all shape nodes in the document
SharedPtr<NodeCollection> shapeCollection = doc->GetChildNodes(Aspose::Words::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
ArrayPtr<SharedPtr<Node>> shapes = shapeCollection->ToArray();
for (auto shape : System::IterateOver(shapes->LINQ_OfType<SharedPtr<Shape> >()))
{
// Filter out all shapes that we don't need
{
// Create a new shape that will replace the existing shape
auto image = MakeObject<Shape>(doc, Aspose::Words::Drawing::ShapeType::Image);
// Load the image into the new shape
image->get_ImageData()->SetImage(ImageDir + u"Windows MetaFile.wmf");
// Make new shape's position to match the old shape
image->set_Left(shape->get_Left());
image->set_Top(shape->get_Top());
image->set_Width(shape->get_Width());
image->set_Height(shape->get_Height());
image->set_RelativeHorizontalPosition(shape->get_RelativeHorizontalPosition());
image->set_RelativeVerticalPosition(shape->get_RelativeVerticalPosition());
image->set_HorizontalAlignment(shape->get_HorizontalAlignment());
image->set_VerticalAlignment(shape->get_VerticalAlignment());
image->set_WrapType(shape->get_WrapType());
image->set_WrapSide(shape->get_WrapSide());
// Insert new shape after the old shape and remove the old shape
shape->get_ParentNode()->InsertAfter(image, shape);
shape->Remove();
}
}
doc->Save(ArtifactsDir + u"Shape.ReplaceTextboxesWithImages.docx");

#include <Aspose.Words.Cpp/Model/Nodes/NodeCollection.h>

+ Inheritance diagram for Aspose::Words::NodeCollection:

Public Member Functions

void Add (SharedPtr< Node > node)
 Adds a node to the end of the collection. More...
 
void Clear ()
 Removes all nodes from this collection and from the document. More...
 
bool Contains (SharedPtr< Node > node)
 Determines whether a node is in the collection. More...
 
SharedPtr< CompositeNodeget_Container () override
 
int32_t get_Count ()
 Gets the number of nodes in the collection. More...
 
SharedPtr< NodeGetCurrentNode () override
 
SharedPtr< IEnumerator< SharedPtr< Node > > > GetEnumerator () override
 Provides a simple "foreach" style iteration over the collection of nodes. More...
 
SharedPtr< NodeGetNextMatchingNode (SharedPtr< Node > curNode) override
 
virtual const TypeInfoGetType () const override
 
SharedPtr< Nodeidx_get (int32_t index)
 Retrieves a node at the given index. More...
 
int32_t IndexOf (SharedPtr< Node > node)
 Returns the zero-based index of the specified node. More...
 
void Insert (int32_t index, SharedPtr< Node > node)
 Inserts a node into the collection at the specified index. More...
 
virtual bool Is (const TypeInfo &target) const override
 
void Remove (SharedPtr< Node > node)
 Removes the node from the collection and from the document. More...
 
void RemoveAt (int32_t index)
 Removes the node at the specified index from the collection and from the document. More...
 
ArrayPtr< SharedPtr< Node > > ToArray ()
 Copies all nodes from the collection to a new array of nodes. More...
 
- Public Member Functions inherited from System::Collections::Generic::IEnumerable< System::SharedPtr< Aspose::Words::Node > >
EnumeratorBasedIterator< T, IEnumerator< T > > begin () noexcept
 
EnumeratorBasedIterator< T, IEnumerator< T > > cbegin () noexcept
 
EnumeratorBasedIterator< T, IEnumerator< T > > cend () noexcept
 
EnumeratorBasedIterator< T, IEnumerator< T > > end () noexcept
 
bool LINQ_All (std::function< bool(T)> predicate)
 
bool LINQ_Any ()
 
bool LINQ_Any (std::function< bool(T)> predicate)
 
SharedPtr< IEnumerable< ResultType > > LINQ_Cast ()
 
SharedPtr< IEnumerable< Result > > LINQ_Cast ()
 
bool LINQ_Contains (T value)
 
int LINQ_Count ()
 
int LINQ_Count (const Func< T, bool > &predicate)
 
LINQ_ElementAt (int index)
 
LINQ_First ()
 
LINQ_First (const Func< T, bool > &predicate)
 
LINQ_FirstOrDefault ()
 
LINQ_FirstOrDefault (std::function< bool(T)> predicate)
 
LINQ_Last ()
 
LINQ_LastOrDefault ()
 
SharedPtr< IEnumerable< ResultType > > LINQ_OfType ()
 
SharedPtr< IEnumerable< Result > > LINQ_OfType ()
 
SharedPtr< IEnumerable< Source > > LINQ_OrderBy (const Func< Source, Key > &keySelector)
 
SharedPtr< IEnumerable< T > > LINQ_OrderBy (const Func< T, Key > &keySelector)
 
SharedPtr< IEnumerable< Result > > LINQ_Select (const Func< Source, Result > &selector)
 
SharedPtr< IEnumerable< ResultType > > LINQ_Select (const Func< T, ResultType > &selector)
 
ArrayPtr< T > LINQ_ToArray ()
 
SharedPtr< List< T > > LINQ_ToList ()
 
SharedPtr< IEnumerable< T > > LINQ_Where (std::function< bool(T)> predicate)
 
- Public Member Functions inherited from Object
ASPOSECPP_SHARED_API Object ()
 
ASPOSECPP_SHARED_API Object (Object const &x)
 
virtual ASPOSECPP_SHARED_API ~Object ()
 
virtual ASPOSECPP_SHARED_API bool Equals (ptr obj)
 
Detail::SmartPtrCounter * GetCounter ()
 
virtual ASPOSECPP_SHARED_API int GetHashCode () const
 
ASPOSECPP_SHARED_API void Lock ()
 
virtual ASPOSECPP_SHARED_API ptr MemberwiseClone () const
 
Objectoperator= (Object const &x)
 
bool ReferenceEquals (String const &str, std::nullptr_t)
 
bool ReferenceEquals (String const &str1, String const &str2)
 
int RemovedSharedRefs (int count)
 
virtual ASPOSECPP_SHARED_API void SetTemplateWeakPtr (unsigned int argument)
 
int SharedCount () const
 
ObjectSharedRefAdded ()
 
int SharedRefRemovedSafe ()
 
virtual ASPOSECPP_SHARED_API String ToString () const
 
ASPOSECPP_SHARED_API void Unlock ()
 
Detail::SmartPtrCounter * WeakRefAdded ()
 
void WeakRefRemoved ()
 

Static Public Member Functions

static const TypeInfoType ()
 
- Static Public Member Functions inherited from Object
bool Equals (double const &objA, double const &objB)
 
bool Equals (float const &objA, float const &objB)
 
static std::enable_if<!IsSmartPtr< T1 >::value &&!IsSmartPtr< T2 >::value, bool >::type Equals (T1 const &objA, T2 const &objB)
 
static std::enable_if< IsSmartPtr< T1 >::value &&IsSmartPtr< T2 >::value, bool >::type Equals (T1 const &objA, T2 const &objB)
 
static bool ReferenceEquals (ptr const &objA, ptr const &objB)
 
static std::enable_if<!IsSmartPtr< T >::value, bool >::type ReferenceEquals (T const &objA, std::nullptr_t)
 
static std::enable_if<!IsSmartPtr< T >::value, bool >::type ReferenceEquals (T const &objA, T const &objB)
 
static const TypeInfoType ()
 

Additional Inherited Members

- Public Types inherited from System::Collections::Generic::IEnumerable< System::SharedPtr< Aspose::Words::Node > >
typedef IEnumerator< T > IEnumeratorType
 
typedef T ValueType
 
- Public Types inherited from Object
typedef SmartPtr< Objectptr
 
typedef System::Details::SharedMembersType shared_members_type
 

Member Function Documentation

◆ Add()

void Aspose::Words::NodeCollection::Add ( System::SharedPtr< Aspose::Words::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 ImportNode() to import the node to the current document. The imported node can then be inserted into the current document.

Parameters
nodeThe node to be added to the end of the collection.
Exceptions
System::NotSupportedExceptionThe NodeCollection is a "deep" collection.
Examples

Shows how to prepare a new section node for editing.

auto doc = MakeObject<Document>();
// A blank document comes with a section, which has a body, which in turn has a paragraph,
// so we can edit the document by adding children to the paragraph like shapes or runs of text
ASSERT_EQ(2, doc->get_Sections()->idx_get(0)->GetChildNodes(Aspose::Words::NodeType::Any, true)->get_Count());
// If we add a new section like this, it will not have a body or a paragraph that we can edit
doc->get_Sections()->Add(MakeObject<Section>(doc));
ASSERT_EQ(0, doc->get_Sections()->idx_get(1)->GetChildNodes(Aspose::Words::NodeType::Any, true)->get_Count());
// Makes sure that the section contains a body with at least one paragraph
doc->get_LastSection()->EnsureMinimum();
// Now we can add content to this section
ASSERT_EQ(2, doc->get_Sections()->idx_get(1)->GetChildNodes(Aspose::Words::NodeType::Any, true)->get_Count());

◆ Clear()

void Aspose::Words::NodeCollection::Clear ( )

Removes all nodes from this collection and from the document.

Examples

Shows how to remove all sections from a document.

auto doc = MakeObject<Document>(MyDir + u"Document.docx");
// All of the document's content is stored in the child nodes of sections like this one
ASSERT_EQ(u"Hello World!", doc->GetText().Trim());
ASSERT_EQ(5, doc->get_Sections()->idx_get(0)->GetChildNodes(Aspose::Words::NodeType::Any, true)->get_Count());
doc->get_Sections()->Clear();
// Clearing the section collection effectively empties the document
ASSERT_EQ(String::Empty, doc->GetText());
ASSERT_EQ(0, doc->get_Sections()->get_Count());

◆ Contains()

bool Aspose::Words::NodeCollection::Contains ( System::SharedPtr< Aspose::Words::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
nodeThe node to locate.
Returns
True if item is found in the collection; otherwise, false.
Examples

Shows how to work with a NodeCollection.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// The normal way to insert Runs into a document is to add text using a DocumentBuilder
builder->Write(u"Run 1. ");
builder->Write(u"Run 2. ");
// Every .Write() invocation creates a new Run, which is added to the parent Paragraph's RunCollection
SharedPtr<RunCollection> runs = doc->get_FirstSection()->get_Body()->get_FirstParagraph()->get_Runs();
ASSERT_EQ(2, runs->get_Count());
// We can insert a node into the RunCollection manually to achieve the same effect
auto newRun = MakeObject<Run>(doc, u"Run 3. ");
runs->Insert(3, newRun);
ASSERT_TRUE(runs->Contains(newRun));
ASSERT_EQ(u"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
SharedPtr<Run> run = runs->idx_get(1);
runs->Remove(run);
ASSERT_EQ(u"Run 1. Run 3.", doc->GetText().Trim());
ASSERT_FALSE(run == nullptr);
ASSERT_FALSE(runs->Contains(run));

◆ get_Container()

System::SharedPtr<Aspose::Words::CompositeNode> Aspose::Words::NodeCollection::get_Container ( )
override

◆ get_Count()

int32_t Aspose::Words::NodeCollection::get_Count ( )

Gets the number of nodes in the collection.

Examples

Shows how to enumerate immediate children of a CompositeNode using indexed access.

auto doc = MakeObject<Document>();
auto paragraph = System::DynamicCast<Aspose::Words::Paragraph>(doc->GetChild(Aspose::Words::NodeType::Paragraph, 0, true));
paragraph->AppendChild(MakeObject<Run>(doc, u"Hello world!"));
SharedPtr<Aspose::Words::NodeCollection> children = paragraph->get_ChildNodes();
for (int i = 0; i < children->get_Count(); i++)
{
SharedPtr<Node> child = children->idx_get(i);
// Paragraph may contain children of various types such as runs, shapes and so on
{
auto run = System::DynamicCast<Aspose::Words::Run>(child);
System::Console::WriteLine(run->get_Text());
}
}

◆ GetCurrentNode()

System::SharedPtr<Aspose::Words::Node> Aspose::Words::NodeCollection::GetCurrentNode ( )
override

◆ GetEnumerator()

System::SharedPtr<System::Collections::Generic::IEnumerator<System::SharedPtr<Aspose::Words::Node> > > Aspose::Words::NodeCollection::GetEnumerator ( )
overridevirtual

Provides a simple "foreach" style iteration over the collection of nodes.

Returns
An IEnumerator.

Implements System::Collections::Generic::IEnumerable< System::SharedPtr< Aspose::Words::Node > >.

◆ GetNextMatchingNode()

System::SharedPtr<Aspose::Words::Node> Aspose::Words::NodeCollection::GetNextMatchingNode ( System::SharedPtr< Aspose::Words::Node curNode)
override

◆ GetType()

◆ idx_get()

System::SharedPtr<Aspose::Words::Node> Aspose::Words::NodeCollection::idx_get ( int32_t  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
indexAn index into the collection of nodes.
Examples

Shows how to enumerate immediate children of a CompositeNode using indexed access.

auto doc = MakeObject<Document>();
auto paragraph = System::DynamicCast<Aspose::Words::Paragraph>(doc->GetChild(Aspose::Words::NodeType::Paragraph, 0, true));
paragraph->AppendChild(MakeObject<Run>(doc, u"Hello world!"));
SharedPtr<Aspose::Words::NodeCollection> children = paragraph->get_ChildNodes();
for (int i = 0; i < children->get_Count(); i++)
{
SharedPtr<Node> child = children->idx_get(i);
// Paragraph may contain children of various types such as runs, shapes and so on
{
auto run = System::DynamicCast<Aspose::Words::Run>(child);
System::Console::WriteLine(run->get_Text());
}
}

◆ IndexOf()

int32_t Aspose::Words::NodeCollection::IndexOf ( System::SharedPtr< Aspose::Words::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
nodeThe node to locate.
Returns
The zero-based index of the node within the collection, if found; otherwise, -1.
Examples

Shows how to get the indexes of nodes in the collections that contain them.

auto doc = MakeObject<Document>(MyDir + u"Tables.docx");
auto table = System::DynamicCast<Aspose::Words::Tables::Table>(doc->GetChild(Aspose::Words::NodeType::Table, 0, true));
SharedPtr<NodeCollection> allTables = doc->GetChildNodes(Aspose::Words::NodeType::Table, true);
ASSERT_EQ(0, allTables->IndexOf(table));
SharedPtr<Row> row = table->get_Rows()->idx_get(2);
ASSERT_EQ(2, table->IndexOf(row));
SharedPtr<Cell> cell = row->get_LastCell();
ASSERT_EQ(4, row->IndexOf(cell));

◆ Insert()

void Aspose::Words::NodeCollection::Insert ( int32_t  index,
System::SharedPtr< Aspose::Words::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 ImportNode() to import the node to the current document. The imported node can then be inserted into the current document.

Parameters
indexThe 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.
nodeThe node to insert.
Exceptions
System::NotSupportedExceptionThe NodeCollection is a "deep" collection.
Examples

Shows how to work with a NodeCollection.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// The normal way to insert Runs into a document is to add text using a DocumentBuilder
builder->Write(u"Run 1. ");
builder->Write(u"Run 2. ");
// Every .Write() invocation creates a new Run, which is added to the parent Paragraph's RunCollection
SharedPtr<RunCollection> runs = doc->get_FirstSection()->get_Body()->get_FirstParagraph()->get_Runs();
ASSERT_EQ(2, runs->get_Count());
// We can insert a node into the RunCollection manually to achieve the same effect
auto newRun = MakeObject<Run>(doc, u"Run 3. ");
runs->Insert(3, newRun);
ASSERT_TRUE(runs->Contains(newRun));
ASSERT_EQ(u"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
SharedPtr<Run> run = runs->idx_get(1);
runs->Remove(run);
ASSERT_EQ(u"Run 1. Run 3.", doc->GetText().Trim());
ASSERT_FALSE(run == nullptr);
ASSERT_FALSE(runs->Contains(run));

◆ Is()

◆ Remove()

void Aspose::Words::NodeCollection::Remove ( System::SharedPtr< Aspose::Words::Node node)

Removes the node from the collection and from the document.

Parameters
nodeThe node to remove.
Examples

Shows how to work with a NodeCollection.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// The normal way to insert Runs into a document is to add text using a DocumentBuilder
builder->Write(u"Run 1. ");
builder->Write(u"Run 2. ");
// Every .Write() invocation creates a new Run, which is added to the parent Paragraph's RunCollection
SharedPtr<RunCollection> runs = doc->get_FirstSection()->get_Body()->get_FirstParagraph()->get_Runs();
ASSERT_EQ(2, runs->get_Count());
// We can insert a node into the RunCollection manually to achieve the same effect
auto newRun = MakeObject<Run>(doc, u"Run 3. ");
runs->Insert(3, newRun);
ASSERT_TRUE(runs->Contains(newRun));
ASSERT_EQ(u"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
SharedPtr<Run> run = runs->idx_get(1);
runs->Remove(run);
ASSERT_EQ(u"Run 1. Run 3.", doc->GetText().Trim());
ASSERT_FALSE(run == nullptr);
ASSERT_FALSE(runs->Contains(run));

◆ RemoveAt()

void Aspose::Words::NodeCollection::RemoveAt ( int32_t  index)

Removes the node at the specified index from the collection and from the document.

Parameters
indexThe 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.
Examples

Shows how to add/remove sections in a document.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->Write(u"Section 1");
builder->Write(u"Section 2");
// This shows what is in the document originally. The document has two sections
ASSERT_EQ(u"Section 1\x000c" u"Section 2", doc->GetText().Trim());
// Delete the first section from the document
doc->get_Sections()->RemoveAt(0);
// Duplicate the last section and append the copy to the end of the document
int lastSectionIdx = doc->get_Sections()->get_Count() - 1;
SharedPtr<Section> newSection = doc->get_Sections()->idx_get(lastSectionIdx)->Clone();
doc->get_Sections()->Add(newSection);
// Check what the document contains after we changed it
ASSERT_EQ(u"Section 2\x000c" u"Section 2", doc->GetText().Trim());

◆ ToArray()

System::ArrayPtr<System::SharedPtr<Aspose::Words::Node> > Aspose::Words::NodeCollection::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.
Examples

Shows how to replace all textboxes with images.

auto doc = MakeObject<Document>(MyDir + u"Textboxes in drawing canvas.docx");
// This gets a live collection of all shape nodes in the document
SharedPtr<NodeCollection> shapeCollection = doc->GetChildNodes(Aspose::Words::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
ArrayPtr<SharedPtr<Node>> shapes = shapeCollection->ToArray();
for (auto shape : System::IterateOver(shapes->LINQ_OfType<SharedPtr<Shape> >()))
{
// Filter out all shapes that we don't need
{
// Create a new shape that will replace the existing shape
auto image = MakeObject<Shape>(doc, Aspose::Words::Drawing::ShapeType::Image);
// Load the image into the new shape
image->get_ImageData()->SetImage(ImageDir + u"Windows MetaFile.wmf");
// Make new shape's position to match the old shape
image->set_Left(shape->get_Left());
image->set_Top(shape->get_Top());
image->set_Width(shape->get_Width());
image->set_Height(shape->get_Height());
image->set_RelativeHorizontalPosition(shape->get_RelativeHorizontalPosition());
image->set_RelativeVerticalPosition(shape->get_RelativeVerticalPosition());
image->set_HorizontalAlignment(shape->get_HorizontalAlignment());
image->set_VerticalAlignment(shape->get_VerticalAlignment());
image->set_WrapType(shape->get_WrapType());
image->set_WrapSide(shape->get_WrapSide());
// Insert new shape after the old shape and remove the old shape
shape->get_ParentNode()->InsertAfter(image, shape);
shape->Remove();
}
}
doc->Save(ArtifactsDir + u"Shape.ReplaceTextboxesWithImages.docx");

◆ Type()

static const System::TypeInfo& Aspose::Words::NodeCollection::Type ( )
static
@ Shape
A drawing object, such as an OfficeArt shape, image or an OLE object. A Shape node can contain Paragr...
@ Image
The shape is an image.
static ASPOSECPP_SHARED_API void WriteLine()
std::enable_if_t<!Details::IsIterable< Enumerable >::value, Details::EnumeratorAdapter< Enumerable, T > > IterateOver(System::SmartPtr< Enumerable > enumerable)
@ TextBox
The shape is a textbox. Note that shapes of many other types can also have text inside them too....
@ Run
A run of text.
@ Paragraph
A paragraph of text. A Paragraph node is a container for inline level elements Run,...
@ Table
A Table object that represents a table in a Word document. A Table node can have Row nodes.
@ Any
Indicates all node types. Allows to select all children.
static std::enable_if< IsExceptionWrapper< T >::value, bool >::type Equals(const T &obj, const T2 &another)
@ SectionBreakNewPage
Specifies start of new section on a new page.