GemBox.Document
  • Overview
  • Examples
  • Free version
  • Support
  • Pricelist

    Show / Hide Table of Contents

    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 ModelGemBox.Document Content ModelPicture classPicturePictureDynamic connector.32Dynamic connector.33Dynamic connector.37Dynamic connector.38Shape classShapeShapeDynamic connector.42Dynamic connectorDynamic connector.75Dynamic connector.77PreservedDrawingElement classPreservedDrawingElementPreservedDrawingElementRun classRunRunBookmarkStart classBookmarkStartBookmarkStartBookmarkEnd classBookmarkEndBookmarkEndSpecialCharacter classSpecialCharacterSpecialCharacterPreservedInline classPreservedInlinePreservedInlineSheet.81TextBox classTextBoxTextBoxTextBox.Blocks propertyBlocksBlocksSheet.82Group classGroupGroupGroup.Drawings propertyDrawingsDrawingsSheet.83Note classNoteNoteNote.Blocks propertyBlocksBlocksGroup.84InlineContentControl classInlineContentControlInlineContentControlInlineContentControl.Inlines propertyInlinesInlinesSheet.85Field classFieldFieldField.InstructionInlines propertyInstructionElementsInstructionElementsField.ResultInlines propertyResultElementsResultElementsSheet.86Hyperlink classHyperlinkHyperlinkHyperlink.DisplayInlines propertyDisplayInlinesDisplayInlinesDynamic connector.87Dynamic connector.88Dynamic connector.89Dynamic connector.91Dynamic connector.92Dynamic connector.94Dynamic connector.95Dynamic connector.96Dynamic connector.97Dynamic connector.98Dynamic connector.99Dynamic connector.100Dynamic connector.101Dynamic connector.102Sheet.103Paragraph classParagraphParagraphParagraph.Inlines propertyInlinesInlinesSheet.104TableOfEntries classTableOfEntriesTableOfEntriesTableOfEntries.Entries propertyEntriesEntriesSheet.105Table classTableTableTable.Rows propertyRowsRowsSheet.106HeaderFooter classHeaderFooterHeaderFooterHeaderFooter.Blocks propertyBlocksBlocksSheet.107Section.HeadersFooters propertyHeadersFootersHeadersFootersSection classSectionSectionSection.Blocks propertyBlocksBlocksSheet.108DocumentModel.Sections propertySectionsSectionsDocumentModel classDocumentModelDocumentModelSheet.109BlockContentControl classBlockContentControlBlockContentControlBlockContentControl.Blocks propertyBlocksBlocksSheet.111TableCell classTableCellTableCellTableCell.Blocks propertyBlocksBlocksDynamic connector.113Sheet.116TableRow classTableRowTableRowTableRow.Cells propertyCellsCellsSheet.117Dynamic connector.114Element classElementElementBlock classBlockBlockInline classInlineInlineDynamic connector.47Dynamic connector.49DrawingElement classDrawingElementDrawingElementRectangle.12ChartChartDynamic connector.119CommentStart classCommentStartCommentStartCommentEnd classCommentEndCommentEndDynamic connector.122Dynamic connector.123
    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.

    Back to top

    Facebook • Twitter • LinkedIn

    © GemBox Ltd. — All rights reserved.