Click or drag to resize

Content Model

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

The following sections describe document content model and properties, behaviors and operations common to all Element derived classes:

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.

Navigate to Note.Blocks propertyNavigate to Note classNavigate to DrawingElement classNavigate to DrawingElement.Layout propertyNavigate to Inline classNavigate to Block classNavigate to Element classNavigate to Shape classNavigate to TextBox.Blocks propertyNavigate to TextBox classNavigate to Hyperlink.DisplayInlines propertyNavigate to PreservedInline classNavigate to SpecialCharacter classNavigate to BookmarkEnd classNavigate to BookmarkStart classNavigate to Field classNavigate to Hyperlink classNavigate to Picture classNavigate to Run classNavigate to TableCell.Blocks propertyNavigate to TableCell classNavigate to TableRow.Cells propertyNavigate to TableRow classNavigate to TableOfEntries.Entries propertyNavigate to Table.Rows propertyNavigate to TableOfEntries classNavigate to Table classNavigate to Paragraph.Inlines propertyNavigate to Paragraph classNavigate to HeaderFooter.Blocks propertyNavigate to HeaderFooter classNavigate to Section.Blocks propertyNavigate to Section classNavigate to Section.HeadersFooters propertyNavigate to DocumentModel classNavigate to DocumentModel.Sections propertyNavigate to Field.ResultInlines propertyNavigate to Field.InstructionInlines propertyGemBox.Document Content Model

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 IList interface and modify the collection through IList members.

Caution note 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 TableOfEntriesEntries 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 SectionBlocks 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 ElementCollectionSupportedElementTypes property for each content collection.

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

// 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.

// 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)
            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)
Caution note Caution

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 note 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 ElementClone(Boolean) method to clone the element and insert its clone.

If you want to insert document content element into another document, then use DocumentModelImportT(T, 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 Formattings and Styles.