DocumentModel Class

Namespace:
GemBox.Document
Assembly:
GemBox.Document.dll

Represents a document.

public sealed class DocumentModel : Element, IContentElement
Public NotInheritable Class DocumentModel
    Inherits Element
    Implements IContentElement
Inheritance:
DocumentModel
Implements
Remarks

DocumentModel is a central class in GemBox.Document component. It is an in-memory representation of a document file.

Document content can be retrieved through Sections property. For more information, see content model.

To load / read a document from a file or a stream, use static Load(String) methods. To preserve unsupported file format features, set PreserveUnsupportedFeatures to true. For more information, see preservation.

To save / write a document to a file or a stream use Save(String) methods. For more information, see supported file formats.

DocumentModel contains also following members:

Constructors

DocumentModel()

Initializes a new instance of the DocumentModel class.

public DocumentModel()
Public Sub New

Properties

Bookmarks

Gets the document bookmarks.

public BookmarkCollection Bookmarks { get; }
Public ReadOnly Property Bookmarks As BookmarkCollection
Property Value
BookmarkCollection

The document bookmarks.

See Also

Comments

Gets the document comments.

public CommentCollection Comments { get; }
Public ReadOnly Property Comments As CommentCollection
Property Value
CommentCollection

The document comments.

See Also

CustomXmlParts

Gets the custom XML parts contained in this document.

public CustomXmlPartCollection CustomXmlParts { get; }
Public ReadOnly Property CustomXmlParts As CustomXmlPartCollection
Property Value
CustomXmlPartCollection

The custom XML parts contained in this document.

DefaultCharacterFormat

Gets or sets the default character format.

public CharacterFormat DefaultCharacterFormat { get; set; }
Public Property DefaultCharacterFormat As CharacterFormat
Property Value
CharacterFormat

The default character format.

DefaultParagraphFormat

Gets or sets the default paragraph format.

public ParagraphFormat DefaultParagraphFormat { get; set; }
Public Property DefaultParagraphFormat As ParagraphFormat
Property Value
ParagraphFormat

The default paragraph format.

DocumentProperties

Gets the document properties.

public DocumentProperties DocumentProperties { get; }
Public ReadOnly Property DocumentProperties As DocumentProperties
Property Value
DocumentProperties

The document properties.

ElementType

Gets the ElementType of this Element instance.

public override ElementType ElementType { get; }
Public Overrides ReadOnly Property ElementType As ElementType
Property Value
ElementType

The ElementType of this Element instance.

Overrides

HyphenationDictionaries

Gets the collection of hyphenation dictionaries.

public static HyphenationDictionaryCollection HyphenationDictionaries { get; }
Public Shared ReadOnly Property HyphenationDictionaries As HyphenationDictionaryCollection
Property Value
HyphenationDictionaryCollection

The collection of hyphenation dictionaries.

HyphenationOptions

Gets or sets the document hyphenation options.

public HyphenationOptions HyphenationOptions { get; set; }
Public Property HyphenationOptions As HyphenationOptions
Property Value
HyphenationOptions

The document hyphenation options.

MailMerge

Gets the object that exposes mail merge operations and options for a document.

public MailMerge MailMerge { get; }
Public ReadOnly Property MailMerge As MailMerge
Property Value
MailMerge

The object that exposes mail merge operations and options for a document.

Protection

Gets or sets the document protection settings used to restrict editing and formatting of document content. Supported in DOCX and DOC formats.

public DocumentProtection Protection { get; set; }
Public Property Protection As DocumentProtection
Property Value
DocumentProtection

The document protection settings used to restrict editing and formatting of document content.

Remarks

Document protection is a set of restrictions used to prevent unintentional changes to all or part of a document - since this protection does not encrypt the document, malicious applications may circumvent its use. This protection is not intended as a security feature and may be ignored.

RevisionOptions

Gets or sets the document revision options.

public RevisionOptions RevisionOptions { get; set; }
Public Property RevisionOptions As RevisionOptions
Property Value
RevisionOptions

The document revision options.

Revisions

Contains all revisions in the document.

public RevisionCollection Revisions { get; }
Public ReadOnly Property Revisions As RevisionCollection
Property Value
RevisionCollection

All revisions in the document.

Sections

Gets the document sections.

public SectionCollection Sections { get; }
Public ReadOnly Property Sections As SectionCollection
Property Value
SectionCollection

The document sections.

Remarks

Since Section class is sealed, only supported element in this collection is Section.

Settings

Gets or sets the document settings.

public DocumentSettings Settings { get; set; }
Public Property Settings As DocumentSettings
Property Value
DocumentSettings

The document settings.

Styles

Gets the document styles.

public StyleCollection Styles { get; }
Public ReadOnly Property Styles As StyleCollection
Property Value
StyleCollection

The document styles.

Variables

Gets a dictionary of document variables.

public VariablesDictionary Variables { get; }
Public ReadOnly Property Variables As VariablesDictionary
Property Value
VariablesDictionary

A dictionary of document variables.

See Also

ViewOptions

Gets or sets the document view options.

public ViewOptions ViewOptions { get; set; }
Public Property ViewOptions As ViewOptions
Property Value
ViewOptions

The document view options.

WriteProtection

Gets or sets the document write protection options. Supported only in DOCX and DOC formats.

public WriteProtection WriteProtection { get; set; }
Public Property WriteProtection As WriteProtection
Property Value
WriteProtection

The document write protection options.

Remarks

Write protection refers to a mode in which the document's contents can be edited but the document cannot be resaved using the same file name.

WriteProtection is currently not supported when exporting a document to PDF, XPS or image file formats.

For more information, see DOCX Write Protection example.

Methods

CalculateListItems()

Calculates the list items contained in this document.

public IEnumerable<ListItem> CalculateListItems()
Public Function CalculateListItems As IEnumerable(Of ListItem)
Returns
IEnumerable<ListItem>

A sequence of ListItems contained in this document.

Remarks

List (for example, ordered - with numbers, or unordered - with bullets) appearance in GemBox.Document is defined through ListFormat class that is set on Paragraph's ListFormat property or ParagraphStyle's ListFormat property.

ListFormat is different from other formats (ParagraphFormat and CharacterFormat) because it doesn't directly contain any formatting properties.

It contains a reference to a ListStyle which exposes ListLevelFormats for every list (indentation) level through its ListLevelFormats property.

ListLevelFormats contain direct formatting properties that affect the appearance of the list. Every ListStyle contains exactly 9 ListLevelFormats, one for each possible list (indentation) level.

Paragraph's list (indentation) level can be adjusted with ListLevelNumber property. Paragraph's list-related formatting will then be collected from the ListLevelFormat instance contained in the ListLevelFormats at the position ListLevelNumber. This ListLevelFormat can also be retrieved from the ListLevelFormat property.

ListLevelFormat retrieved from the ListLevelFormat property can be additionally modified to enable overriding property values of ListLevelFormat instance contained in the ListLevelFormats at the position ListLevelNumber on a Paragraph or ParagraphStyle basis.

To create a list in a document, first ListStyle instance has to be created from one of the predefined list style types specified with ListTemplateType enumeration. After that, ListFormat can be created with a specified ListStyle and assigned to a Paragraph's ListFormat property. For a complete example, see Lists example.

If ListStyle is not referenced from anywhere in the document (from any Paragraph or ParagraphStyle, then it won't be saved to a Word Document (DOCX) file, unless it is added to Styles collection.

Paragraph's list content, which prefixes paragraph content, is represented by ListItem type.

ListItems are not permanently stored in model nor they are written to file formats which fully support ListFormat, instead they are recreated each time CalculateListItems() method is called.

If document content or formatting is changed, then CalculateListItems() method should be called again to retrieve the latest list items.

For convenience, after calling CalculateListItems() method, ListItem can also be retrieved from ListItem property.

After calling Dispose() on IEnumerator<T> instance retrieved by calling GetEnumerator() on instance returned from CalculateListItems() method, paragraph's ListItem property will be null even if paragraph's IsList is true. This enables easy iteration over ListItems returned from CalculateListItems() method by using foreach statement and removing all references to ListItems after the iteration is finished.

Clone(Boolean)

Clones this DocumentModel instance.

public DocumentModel Clone(bool cloneDescendants)
Public Function Clone(cloneDescendants As Boolean) As DocumentModel
Parameters
cloneDescendants
Boolean

If set to true clone all descendants recursively; otherwise clone only current DocumentModel.

Returns
DocumentModel

ConvertToImageSource(ImageSaveOptions)

Converts single page specified in options of this DocumentModel instance to an ImageSource instance.

public ImageSource ConvertToImageSource(ImageSaveOptions options)
Public Function ConvertToImageSource(options As ImageSaveOptions) As ImageSource
Parameters
options
ImageSaveOptions

The options used when converting a single document's page to an image.

Returns
ImageSource

A new ImageSource instance created from a single document's page specified in options.

See Also

ConvertToXpsDocument(XpsSaveOptions)

Converts this DocumentModel instance to an XpsDocument instance.

public XpsDocument ConvertToXpsDocument(XpsSaveOptions options)
Public Function ConvertToXpsDocument(options As XpsSaveOptions) As XpsDocument
Parameters
options
XpsSaveOptions

The options used when converting to XML Paper Specification (XPS) document.

Returns
XpsDocument

A new XpsDocument instance created from this DocumentModel instance.

See Also

GetPaginator()

Gets the document paginator.

public DocumentModelPaginator GetPaginator()
Public Function GetPaginator As DocumentModelPaginator
Returns
DocumentModelPaginator

The document paginator.

GetPaginator(PaginatorOptions)

Gets the document paginator and updates the document based on the specified options.

public DocumentModelPaginator GetPaginator(PaginatorOptions options)
Public Function GetPaginator(options As PaginatorOptions) As DocumentModelPaginator
Parameters
options
PaginatorOptions

The paginator options used to specify which parts of the document to update while paginating it.

Returns
DocumentModelPaginator

The document paginator.

Import<T>(T, Boolean)

Imports (clones) the specified source element to this DocumentModel instance so it can be inserted into document content.

public T Import<T>(T sourceElement, bool importDescendants)
    where T : Element
Public Function Import(Of T As Element)(sourceElement As T, importDescendants As Boolean) As T
Parameters
sourceElement
T

The source element.

importDescendants
Boolean

true to import source element descendants; otherwise false.

Returns
T

Imported (cloned) source element that can be inserted in this DocumentModel instance.

Type Parameters
T

The Element type to import.

Import<T>(T, Boolean, ImportMapping)

Imports (clones) the specified source element to this DocumentModel instance so it can be inserted into document content.

public T Import<T>(T sourceElement, bool importDescendants, ImportMapping importMapping)
    where T : Element
Public Function Import(Of T As Element)(sourceElement As T, importDescendants As Boolean, importMapping As ImportMapping) As T
Parameters
sourceElement
T

The source element.

importDescendants
Boolean

true to import source element descendants; otherwise false.

importMapping
ImportMapping

Mapping used to match source and destination document styles and other referenced objects.

Returns
T

Imported (cloned) source element that can be inserted in this DocumentModel instance.

Type Parameters
T

The Element type to import.

Import<T>(T, Boolean, Boolean)

Imports (clones) the specified source element to this DocumentModel instance so it can be inserted into document content.

public T Import<T>(T sourceElement, bool importDescendants, bool useDestinationStyles)
    where T : Element
Public Function Import(Of T As Element)(sourceElement As T, importDescendants As Boolean, useDestinationStyles As Boolean) As T
Parameters
sourceElement
T

The source element.

importDescendants
Boolean

true to import source element descendants; otherwise false.

useDestinationStyles
Boolean

true to use destination document (this DocumentModel instance) styles; otherwise false to use source document styles.

Returns
T

Imported (cloned) source element that can be inserted in this DocumentModel instance.

Type Parameters
T

The Element type to import.

Load(Stream)

Loads a document from the specified stream. This method tries to dynamically determine the file format. If you know the file format, it is more reliable and faster to use Load(Stream, LoadOptions) method.

public static DocumentModel Load(Stream stream)
Public Shared Function Load(stream As Stream) As DocumentModel
Parameters
stream
Stream

The stream from which to load a document.

Returns
DocumentModel

A loaded document.

Load(Stream, LoadOptions)

Loads a document from the specified stream.

public static DocumentModel Load(Stream stream, LoadOptions options)
Public Shared Function Load(stream As Stream, options As LoadOptions) As DocumentModel
Parameters
stream
Stream

The stream from which to load a document.

options
LoadOptions

The loading options which can be used to define settings for load operation.

Returns
DocumentModel

A loaded document.

Load(String)

Loads a document from a file with the specified path.

public static DocumentModel Load(string path)
Public Shared Function Load(path As String) As DocumentModel
Parameters
path
String

The path from which to load a document.

Returns
DocumentModel

A loaded document.

Remarks

File extension that is extracted from the path is used to create the appropriate LoadOptions derived class instance that is then passed to the Load(String, LoadOptions) method.

Following file extensions are supported:

  • Microsoft Word: .docx, .docm, .dotm, .dotx
  • Microsoft Word 97-2003: .doc, .dot
  • HyperText Markup Language: .htm, .html, .mht, .mhtml
  • Rich Text Format: .rtf
  • Portable Document Format: .pdf
  • Plain Text: .txt
Exceptions
InvalidOperationException

If file extension is not specified or not supported. If file extension is not recognized, use Load(String, LoadOptions) method overload instead.

PlatformNotSupportedException

File extension is not supported on the current platform.

Load(String, LoadOptions)

Loads a document from a file with the specified path.

public static DocumentModel Load(string path, LoadOptions options)
Public Shared Function Load(path As String, options As LoadOptions) As DocumentModel
Parameters
path
String

The path from which to load a document.

options
LoadOptions

The loading options which can be used to define settings for load operation.

Returns
DocumentModel

A loaded document.

Print()

Prints the document to the default printer.

public void Print()
Public Sub Print

Print(String)

Prints the document to the specified printer.

public void Print(string printerName)
Public Sub Print(printerName As String)
Parameters
printerName
String

Printer name.

Print(String, PrintOptions)

Prints the document to the specified printer according to specified options.

public void Print(string printerName, PrintOptions options)
Public Sub Print(printerName As String, options As PrintOptions)
Parameters
printerName
String

Printer name.

options
PrintOptions

Print options.

Save(Stream, SaveOptions)

Saves the document in the specified stream.

[ComVisible(false)]
public void Save(Stream stream, SaveOptions options)
<ComVisible(False)>
Public Sub Save(stream As Stream, options As SaveOptions)
Parameters
stream
Stream

The stream in which to save the document.

options
SaveOptions

The saving options which can be used to define settings for save operation.

Save(Object, String)

Saves the document to a System.Web.HttpResponse or System.Web.HttpResponseBase output stream or a System.Net.Http.HttpResponseMessage and sets appropriate HTTP response headers (Content-Type and Content-Disposition). Use this method in ASP.NET application to send the document to a client browser. File format is resolved from fileName extension. See remarks why httpResponse parameter is of type Object.

[ComVisible(false)]
public void Save(object httpResponse, string fileName)
<ComVisible(False)>
Public Sub Save(httpResponse As Object, fileName As String)
Parameters
httpResponse
Object

System.Web.HttpResponse object that can be retrieved through the Response property of the System.Web.HttpApplication, System.Web.HttpContext, System.Web.UI.Page or System.Web.UI.UserControl classes or System.Web.HttpResponseBase object or System.Net.Http.HttpResponseMessage object.

fileName
String

File name that will be presented in client browser when downloading a file.

Remarks
note

Supported only if updating the whole page with a postback and not if doing partial-page updates (when you use UpdatePanel controls to update selected regions of a page).

This method accepts Object rather than HttpResponse, HttpResponseBase or HttpResponseMessage because otherwise GemBox.Document assembly would have a dependency on System.Web or System.Net.Http assemblies and could not be used in applications which target Client Profile .NET Framework.

HttpResponse can be retrieved through the Response property of the HttpApplication, HttpContext, Page or UserControl classes.

For supported file extensions, see remarks for Save(String) method.

Exceptions
InvalidOperationException

If file extension is not specified or not supported. If file extension is not recognized, use Save(Object, String, SaveOptions) method overload instead.

Save(Object, String, SaveOptions)

Saves the document to a System.Web.HttpResponse or System.Web.HttpResponseBase output stream or a System.Net.Http.HttpResponseMessage and sets appropriate HTTP response headers (Content-Type and Content-Disposition). Use this method in ASP.NET application to send the document to a client browser. File format is defined with options parameter. See remarks why httpResponse parameter is of type Object.

[ComVisible(false)]
public void Save(object httpResponse, string fileName, SaveOptions options)
<ComVisible(False)>
Public Sub Save(httpResponse As Object, fileName As String, options As SaveOptions)
Parameters
httpResponse
Object

System.Web.HttpResponse object that can be retrieved through the Response property of the System.Web.HttpApplication, System.Web.HttpContext, System.Web.UI.Page or System.Web.UI.UserControl classes or System.Web.HttpResponseBase object or System.Net.Http.HttpResponseMessage object.

fileName
String

File name that will be presented in client browser when downloading a file.

options
SaveOptions

The saving options which can be used to define settings for save operation.

Remarks
note

Supported only if updating the whole page with a postback and not if doing partial-page updates (when you use UpdatePanel controls to update selected regions of a page).

This method accepts Object rather than HttpResponse, HttpResponseBase or HttpResponseMessage because otherwise GemBox.Document assembly would have a dependency on System.Web or System.Net.Http assemblies and could not be used in applications which target Client Profile .NET Framework.

HttpResponse can be retrieved through the Response property of the HttpApplication, HttpContext, Page or UserControl classes.

Save(String)

Saves the document to a file with the specified path. Path must include file extension.

[ComVisible(true)]
public void Save(string path)
<ComVisible(True)>
Public Sub Save(path As String)
Parameters
path
String

The path to which to save the document.

Remarks

File extension that is extracted from the path is used to create the appropriate SaveOptions derived class instance that is then passed to the Save(String, SaveOptions) method.

Following file extensions are supported:

  • Microsoft Word: .docx, .docm, .dotm, .dotx
  • Portable Document Format: .pdf
  • XML Paper Specification: .xps
  • HyperText Markup Language: .htm, .html, .mht, .mhtml
  • Rich Text Format: .rtf
  • Plain Text: .txt
  • Image: .bmp, .gif, .jpg, .jpeg, .png, .tif, .tiff, .wdp
Exceptions
InvalidOperationException

If file extension is not specified or not supported. If file extension is not recognized, use Save(String, SaveOptions) method overload instead.

PlatformNotSupportedException

File extension is not supported on the current platform.

Save(String, SaveOptions)

Saves the document to a file with the specified path.

[ComVisible(false)]
public void Save(string path, SaveOptions options)
<ComVisible(False)>
Public Sub Save(path As String, options As SaveOptions)
Parameters
path
String

The path to which to save the document.

options
SaveOptions

The saving options which can be used to define settings for save operation.

Save(XmlWriter, HtmlSaveOptions)

Save the document to HTML format using the specified writer.

[ComVisible(false)]
public void Save(XmlWriter writer, HtmlSaveOptions options)
<ComVisible(False)>
Public Sub Save(writer As XmlWriter, options As HtmlSaveOptions)
Parameters
writer
XmlWriter

The writer which is used to save the document.

options
HtmlSaveOptions

The HTML saving options which can be used to define settings for save operation.

Inherited Properties

Content

Gets the content of the current Element.

(Inherited from Element)

Document

Gets the owner document.

(Inherited from Element)

Parent

Gets the parent of this Element instance.

(Inherited from Element)

ParentCollection

Gets the ElementCollection that contains this Element instance.

(Inherited from Element)

Inherited Methods

GetChildElements(Boolean)

Gets the child elements.

(Inherited from Element)

GetChildElements(Boolean, ElementType[])

Gets the child elements filtered by ElementType.

(Inherited from Element)

Implements

Examples