Field Class

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

Provides a mechanism for placeholders, such as page reference numbers, which can be added to a document such that those placeholders are replaced by their corresponding values when the document is rendered for display or print.

public sealed class Field : Inline, IContentElement
Public NotInheritable Class Field
    Inherits Inline
    Implements IContentElement
Inheritance:
Field
Implements
Remarks

Fields are used in a mail merge and, usually, in scenarios where document information can be resolved only when document is rendered (for example, page numbers).

GemBox.Document supports nested fields - another field can be contained in an InstructionInlines or a ResultInlines properties of a field.

Fields are defined by the FieldType and, optionally, InstructionInlines that usually contains field arguments and switches, but can also contain other fields, and ResultInlines that contains the latest field's value.

For a field creation example, see fields example.

Constructors

Field(DocumentModel, FieldType)

Initializes a new instance of the Field class.

public Field(DocumentModel document, FieldType fieldType)
Public Sub New(document As DocumentModel, fieldType As FieldType)
Parameters
document
DocumentModel

The owner document.

fieldType
FieldType

The field type.

Field(DocumentModel, FieldType, Inline[])

Initializes a new instance of the Field class.

public Field(DocumentModel document, FieldType fieldType, params Inline[] instructionInlines)
Public Sub New(document As DocumentModel, fieldType As FieldType, ParamArray instructionInlines As Inline())
Parameters
document
DocumentModel

The owner document.

fieldType
FieldType

The field type.

instructionInlines
Inline[]

The Inline sequence that represents field instruction.

Field(DocumentModel, FieldType, IEnumerable<Inline>, Inline[])

Initializes a new instance of the Field class.

public Field(DocumentModel document, FieldType fieldType, IEnumerable<Inline> instructionInlines, params Inline[] resultInlines)
Public Sub New(document As DocumentModel, fieldType As FieldType, instructionInlines As IEnumerable(Of Inline), ParamArray resultInlines As Inline())
Parameters
document
DocumentModel

The owner document.

fieldType
FieldType

The field type.

instructionInlines
IEnumerable<Inline>

The Inline sequence that represents field instruction.

resultInlines
Inline[]

The Inline sequence that represents field result.

Field(DocumentModel, FieldType, IEnumerable<Inline>, IEnumerable<Inline>)

Initializes a new instance of the Field class.

public Field(DocumentModel document, FieldType fieldType, IEnumerable<Inline> instructionInlines, IEnumerable<Inline> resultInlines)
Public Sub New(document As DocumentModel, fieldType As FieldType, instructionInlines As IEnumerable(Of Inline), resultInlines As IEnumerable(Of Inline))
Parameters
document
DocumentModel

The owner document.

fieldType
FieldType

The field type.

instructionInlines
IEnumerable<Inline>

The Inline sequence that represents field instruction.

resultInlines
IEnumerable<Inline>

The Inline sequence that represents field result.

Field(DocumentModel, FieldType, String, Inline[])

Initializes a new instance of the Field class.

public Field(DocumentModel document, FieldType fieldType, string instructionText, params Inline[] resultInlines)
Public Sub New(document As DocumentModel, fieldType As FieldType, instructionText As String, ParamArray resultInlines As Inline())
Parameters
document
DocumentModel

The owner document.

fieldType
FieldType

The field type.

instructionText
String

The field instruction text.

resultInlines
Inline[]

The Inline sequence that represents field result.

Field(DocumentModel, FieldType, String, IEnumerable<Inline>)

Initializes a new instance of the Field class.

public Field(DocumentModel document, FieldType fieldType, string instructionText, IEnumerable<Inline> resultInlines)
Public Sub New(document As DocumentModel, fieldType As FieldType, instructionText As String, resultInlines As IEnumerable(Of Inline))
Parameters
document
DocumentModel

The owner document.

fieldType
FieldType

The field type.

instructionText
String

The field instruction text.

resultInlines
IEnumerable<Inline>

The Inline sequence that represents field result.

Field(DocumentModel, FieldType, String, String)

Initializes a new instance of the Field class.

public Field(DocumentModel document, FieldType fieldType, string instructionText, string resultText)
Public Sub New(document As DocumentModel, fieldType As FieldType, instructionText As String, resultText As String)
Parameters
document
DocumentModel

The owner document.

fieldType
FieldType

The field type.

instructionText
String

The field instruction text.

resultText
String

The field result text.

Properties

CharacterFormat

Gets or sets the character format.

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

The character format.

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

FieldType

Gets the field type.

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

The field type.

FormData

Gets the form related data associated with the parent form field or null if parent field is not form field.

public FormFieldData FormData { get; }
Public ReadOnly Property FormData As FormFieldData
Property Value
FormFieldData

The form related data associated with the parent form field or null if parent field is not form field.

InstructionInlines

Gets the field instruction Inlines.

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

The field instruction Inlines.

Remarks

This collection is not considered to be a part of document content because field's instructions are a part of field's definition. Its type, InlineCollection, was used as a convenience so we can support both instruction text and nested fields. Because of it, IContentElement on a Field will not return InstructionInlines in a Content property.

All Inline derived elements are supported in this collection.

IsDirty

Gets or sets a value indicating whether the result of this Field is invalid and, because of that, it should be updated.

public bool IsDirty { get; set; }
Public Property IsDirty As Boolean
Property Value
Boolean

true if result of this Field is invalid and, because of that, it should be updated; otherwise, false.

Remarks

The property value of true specifies that the result of this field is no longer based on the contents of the document, and should be recalculated whenever an application with this functionality reads the document (for example MS Word).

IsLocked

Gets or sets a value indicating whether this Field is locked and, because of that, it should not be updated.

public bool IsLocked { get; set; }
Public Property IsLocked As Boolean
Property Value
Boolean

true if result of this Field is locked and, because of that, it should not be updated; otherwise, false.

Remarks

This property is simply written to a Word document and has no effect on the behavior of this library. When a field is locked, Word applications will not update its results.

ListItem

Gets the list item or null if field doesn't have list item or its FieldType is not ListNum.

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

The list item or null if field doesn't have list item or its FieldType is not ListNum.

ResultInlines

Gets the field result Inlines.

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

The field result Inlines.

Remarks

All Inline derived elements are supported in this collection.

Methods

Clone(Boolean)

Clones this Field instance, and optionally clones it's result.

public Field Clone(bool cloneResult)
Public Function Clone(cloneResult As Boolean) As Field
Parameters
cloneResult
Boolean

true to clone field result; otherwise false.

Returns
Field

Cloned Field.

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.

GetInstructionText()

Gets the field instruction text if InstructionInlines contains only Run, SpecialCharacter, InlineContentControl elements and bookmarks; otherwise Empty.

public string GetInstructionText()
Public Function GetInstructionText As String
Returns
String

The field instruction text if InstructionInlines contains only Run, SpecialCharacter, InlineContentControl elements and bookmarks; otherwise Empty.

Update()

Updates the ResultInlines of the current Field.

public void Update()
Public Sub Update
Remarks

To update page related fields (Page, PageRef, NumPages, Section and SectionPages) and Seq field create an instance of PaginatorOptions, set its UpdateFields to true and call the GetPaginator(PaginatorOptions) method with that PaginatorOptions instance.

To update mail merge related fields (MergeField, MergeRec, MergeSeq, etc.) call the Execute(Object) method and provide it the data source object.

This Update() method currently supports updating following field types:

More field types can be expected to be supported in a future versions of GemBox.Document.

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 InlineCollection that contains this Inline instance.

(Inherited from Inline)

Revision

Gets or sets the revision information for the inline.

(Inherited from Inline)

Inherited Methods

GetChildElements(Boolean)

Gets the child elements.

(Inherited from Element)

GetChildElements(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

Examples