Content Model

GemBox.Document presents document content as a tree structure with a DocumentModel as a root node.

GemBox.Document Content Model

The following diagram shows GemBox.Document content model hierarchy - a parent / child relationship between document elements.

At the bottom of the content model diagram is a class diagram showing the base document content classes. These classes are abstract. Concrete derivatives for each of these base classes are represented in the content model diagram with the same color as the base class.

Each class and property in the diagram links to its help page, so you can easily navigate to details of each document content member.

GemBox.Document content model diagram

IContentElement interface and ElementCollection class

All document content elements which have a content of their own, also implement IContentElement interface.

This interface enables you to generically traverse and modify the document content.

All content collections, such as SectionCollection, BlockCollection, InlineCollection and others, derive from ElementCollection.

This collection enables traversal and modification of its content in a covariant, type-safe way. For non-type-safe modifications, cast it to interface and modify the collection through members.

Caution

Although all content collections are strongly typed, they may not support all content elements that derive from the collection element type.

For example, BlockCollection returned from the Entries property supports only Paragraphs as its content, although both Table and TableOfEntries, also derive from the BlockCollection element type - Block. On the other hand, BlockCollection returned from the Blocks property supports all Block derived elements as its content.

Supported elements for each content property are documented in the Remarks section of that property or they can be programmatically retrieved through SupportedElementTypes property for each content collection.

The following example shows how to delete all pictures from the document using only IContentElement interface and ElementCollection class.

C#
VB.NET

// Deletes all pictures from the document.
static void DeletePictures()
{
    // Load a document.
    var doc = DocumentModel.Load("Document.docx", LoadOptions.DocxDefault);

    // Delete all pictures from all ElementCollections in the document.
    ForEachContentCollection(doc, RemovePictures);

    // Save a document.
    doc.Save("Document.docx");
}

// Performs the action on each ElementCollection under the element. 
static void ForEachContentCollection(IContentElement element, Action<ElementCollection> action)
{
    if (element != null)
        foreach (var collection in element.Content)
        {
            action(collection);
            foreach (var item in collection)
                ForEachContentCollection(item as IContentElement, action);
        }
}

// Removes all pictures from the collection.
static void RemovePictures(ElementCollection collection)
{
    for (int i = collection.Count - 1; i >= 0; --i)
        if (collection[i].ElementType == ElementType.Picture)
            collection.RemoveAt(i);
}

' Deletes all pictures from the document.
Sub DeletePictures()
    ' Load a document.
    Dim doc = DocumentModel.Load("Document.docx", LoadOptions.DocxDefault)

    ' Delete all pictures from all ElementCollections in the document.
    ForEachContentCollection(doc, AddressOf RemovePictures)

    ' Save a document.
    doc.Save("Document.docx")
End Sub

' Performs the action on each ElementCollection under the element. 
Sub ForEachContentCollection(element As IContentElement, action As Action(Of ElementCollection))
    If element IsNot Nothing Then
        For Each collection In element.Content
            action(collection)
            For Each item In collection
                ForEachContentCollection(TryCast(item, IContentElement), action)
            Next
        Next
    End If
End Sub

' Removes all pictures from the collection.
Sub RemovePictures(collection As ElementCollection)
    For i = collection.Count - 1 To 0 Step -1
        If collection(i).ElementType = ElementType.Picture Then
            collection.RemoveAt(i)
        End If
    Next
End Sub

Warning

Never rely on or hardcode element position in a collection between successive document saving and loading because GemBox.Document compacts in-memory document content while loading a document.

For example, document content created with statement doc.Sections.Add(new Section(doc, new Paragraph(doc, new Run(doc, "Some "), new Run(doc, "text")))); after saving and loading a document again, will have only one Run instance with text Some text, because previous Runs had the same formatting properties, so their text was merged into a single Run instance.

For referencing document content part between successive document saving and loading use BookmarkStart and BookmarkEnd elements or Field element (with DocVariable field type, for example).

Clone and Import

Important

Document content element instance can exist only in one place in the document.

If you want to duplicate document content element and insert it into some other part of the same document, then use Element.Clone(Boolean) method to clone the element and insert its clone.

If you want to insert document content element into another document, then use DocumentModel.Import(Boolean, Boolean) to clone the element into another document and insert the clone.

While importing the element and its descendants, you can choose to also import styles which the element and its descendants use. If parameter useDestinationStyles is true, styles won't be imported - styles with same name from the destination document will be used instead; otherwise, if false, styles will also be imported into the destination document and will, possibly, be renamed to remove the conflicts if styles with the same name already exist in the destination document. For more information about styles and formatting, see formats and styles.