Paragraph Class

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

Represents a paragraph of content in the document.

public sealed class Paragraph : Block, IContentElement
Public NotInheritable Class Paragraph
    Inherits Block
    Implements IContentElement
Inheritance:
System.Object
Paragraph
Implements
Remarks

Paragraph is one of the main document building blocks. It can be contained under a Section, TableCell, TextBox, TableOfEntries or HeaderFooter.

Paragraph is a content element that contains Inline derived elements in its Inlines property. For more information, see content model.

Paragraph can be formatted using the ParagraphFormat property, and it can also be formatted to be used as a part of the list using the ListFormat property. For more information about paragraph formatting, see paragraph formatting example.

Constructors

Paragraph(DocumentModel)

Initializes a new instance of the Paragraph class.

public Paragraph(DocumentModel document)
Public Sub New(document As DocumentModel)
Parameters
document
DocumentModel

The owner document.

Paragraph(DocumentModel, Inline[])

Initializes a new instance of the Paragraph class with specified Inline.

public Paragraph(DocumentModel document, params Inline[] items)
Public Sub New(document As DocumentModel, ParamArray items As Inline())
Parameters
document
DocumentModel

The owner document.

items
Inline[]

The paragraph content.

Paragraph(DocumentModel, IEnumerable<Inline>)

Initializes a new instance of the Paragraph class with specified Inline.

public Paragraph(DocumentModel document, IEnumerable<Inline> items)
Public Sub New(document As DocumentModel, items As IEnumerable(Of Inline))
Parameters
document
DocumentModel

The owner document.

items
System.Collections.Generic.IEnumerable<Inline>

The paragraph content.

Paragraph(DocumentModel, String)

Initializes a new instance of the Paragraph class with specified text.

public Paragraph(DocumentModel document, string text)
Public Sub New(document As DocumentModel, text As String)
Parameters
document
DocumentModel

The owner document.

text
System.String

The paragraph text.

Properties

CharacterFormatForParagraphMark

Gets or sets the character format for the paragraph mark.

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

The character format for the paragraph mark.

CharacterFormatForParagraphMarkRevision

Gets or sets the revision of the character format for the paragraph mark. This property contains the format which was applied before the revision.

public CharacterFormatRevision CharacterFormatForParagraphMarkRevision { get; set; }
Public Property CharacterFormatForParagraphMarkRevision As CharacterFormatRevision
Property Value
CharacterFormatRevision

The revision of the character format for the paragraph mark.

Remarks

The revision is internally stored as a member of CharacterFormatForParagraphMark. Using set property on CharacterFormatForParagraphMark overrides this revision.

Document

Gets the owner document.

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

The owner document.

Overrides

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

Inlines

Gets the Paragraph's inlines.

public InlineCollection Inlines { get; }
Public ReadOnly Property Inlines As InlineCollection
Property Value
InlineCollection

The Paragraph's inlines.

Remarks

All Inline derived elements are supported in this collection.

ListFormat

Gets or sets the list format.

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

The list format.

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 System.IDisposable.Dispose() on System.Collections.Generic.IEnumerator<T> instance retrieved by calling System.Collections.Generic.IEnumerable<T>.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.

ListItem

Gets the list item or null if paragraph doesn't have list item.

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

The list item or null if paragraph doesn't have list item.

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 System.IDisposable.Dispose() on System.Collections.Generic.IEnumerator<T> instance retrieved by calling System.Collections.Generic.IEnumerable<T>.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.

ParagraphFormat

Gets or sets the paragraph format.

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

The paragraph format.

Remarks

For more information about paragraph formatting, see paragraph formatting example.

ParagraphFormatRevision

Gets or sets the revision of the format of this paragraph. This property contains the format which was applied to this paragraph before the revision.

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

The revision of the format of this paragraph.

Remarks

The revision is internally stored as a member of ParagraphFormat. Using set property on ParagraphFormat overrides this revision.

Revision

Gets or sets the revision information for the paragraph.

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

The revision information for the paragraph.

Remarks

If the revision is of the Insert type it means that this paragraph and the following paragraph were a single paragraph before applying this revision. If the revision is of the Delete type it means that this paragraph and the following paragraph were separate paragraphs but they were joined after applying this revision. The revision is internally stored as a member of CharacterFormatForParagraphMark. Using set property on CharacterFormatForParagraphMark overrides this revision.

Methods

Clone(Boolean)

Clones this Paragraph instance.

public Paragraph Clone(bool cloneDescendants)
Public Function Clone(cloneDescendants As Boolean) As Paragraph
Parameters
cloneDescendants
System.Boolean

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

Returns
Paragraph

Cloned Paragraph.

Remarks

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

If you want to insert document content element into some other part of the same document, then clone the element and insert its clone.

If you want to insert document content element into another document, then you should first import it into another document with Import<T>(T, Boolean, Boolean) method and then insert the imported element.

For more information, see cloning example.

Inherited Properties

Content

Gets the content of the current Element.

(Inherited from Element)

Parent

Gets the parent of this Element instance.

(Inherited from Element)

ParentCollection

Gets the BlockCollection that contains this Block instance.

(Inherited from Block)

Inherited Methods

GetChildElements(System.Boolean)

Gets the child elements.

(Inherited from Element)

GetChildElements(System.Boolean, ElementType[])

Gets the child elements filtered by ElementType.

(Inherited from Element)

GetParentElements()

Gets the parent elements.

(Inherited from Element)

GetParentElements(ElementType[])

Gets the parent elements.

(Inherited from Element)

Implements