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:
System.Object
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 InstructionElements or a ResultElements properties of a field.

Fields are defined by the FieldType and, optionally, InstructionElements that usually contains field arguments and switches, but can also contain other fields, and ResultElements 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, Element[])

Initializes a new instance of the Field class.

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

The owner document.

fieldType
FieldType

The field type.

instructionElements
Element[]

The Element sequence that represents field instruction.

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

Initializes a new instance of the Field class.

public Field(DocumentModel document, FieldType fieldType, IEnumerable<Element> instructionElements, params Element[] resultElements)
Public Sub New(document As DocumentModel, fieldType As FieldType, instructionElements As IEnumerable(Of Element), ParamArray resultElements As Element())
Parameters
document
DocumentModel

The owner document.

fieldType
FieldType

The field type.

instructionElements
System.Collections.Generic.IEnumerable<Element>

The Element sequence that represents field instruction.

resultElements
Element[]

The Element sequence that represents field result.

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

Initializes a new instance of the Field class.

public Field(DocumentModel document, FieldType fieldType, IEnumerable<Element> instructionElements, IEnumerable<Element> resultElements)
Public Sub New(document As DocumentModel, fieldType As FieldType, instructionElements As IEnumerable(Of Element), resultElements As IEnumerable(Of Element))
Parameters
document
DocumentModel

The owner document.

fieldType
FieldType

The field type.

instructionElements
System.Collections.Generic.IEnumerable<Element>

The Element sequence that represents field instruction.

resultElements
System.Collections.Generic.IEnumerable<Element>

The Element sequence that represents field result.

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

Initializes a new instance of the Field class.

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

The owner document.

fieldType
FieldType

The field type.

instructionText
System.String

The field instruction text.

resultElements
Element[]

The Element sequence that represents field result.

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

Initializes a new instance of the Field class.

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

The owner document.

fieldType
FieldType

The field type.

instructionText
System.String

The field instruction text.

resultElements
System.Collections.Generic.IEnumerable<Element>

The Element 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
System.String

The field instruction text.

resultText
System.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.

InstructionElements

Gets the field instruction Elements.

public ElementCollection<Element> InstructionElements { get; }
Public ReadOnly Property InstructionElements As ElementCollection(Of Element)
Property Value
ElementCollection<Element>

The field instruction Elements.

Remarks

This collection is not considered to be a part of document content because field's instructions are a part of field's definition. Because of it, IContentElement on a Field will not return InstructionElements in a Content property.

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
System.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
System.Boolean

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

Remarks

When a field is locked, Word application won't update its result. In that case GemBox.Document as well won't update the field result when paginating or rendering the document (to PDF or image).

See Also

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.

ResultElements

Gets the field result Elements.

public ElementCollection<Element> ResultElements { get; }
Public ReadOnly Property ResultElements As ElementCollection(Of Element)
Property Value
ElementCollection<Element>

The field result Elements.

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

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

The field instruction text.

Update()

Updates the ResultElements of the current Field.

public void Update()
Public Sub Update
Remarks

To update page related fields (Page, PageRef, NumPages, Section and SectionPages), NoteRef 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(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

Examples