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.

C#
VB.NET

public sealed class Field : Inline, IContentElement

Public NotInheritable Class Field
    Inherits Inline
    Implements IContentElement

Inheritance:: Object
Element
Inline
Field

Implements

IContentElement

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.

C#
VB.NET

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.

C#
VB.NET

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.

C#
VB.NET

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.

C#
VB.NET

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.

C#
VB.NET

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.

C#
VB.NET

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.

C#
VB.NET

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.

C#
VB.NET

public CharacterFormat CharacterFormat { get; set; }

Public Property CharacterFormat As CharacterFormat

Property Value

CharacterFormat

The character format.

Document

Gets the owner document.

C#
VB.NET

public override DocumentModel Document { get; }

Public Overrides ReadOnly Property Document As DocumentModel

Property Value

DocumentModel

The owner document.

Overrides

Element.Document

ElementType

Gets the ElementType of this Element instance.

C#
VB.NET

public override ElementType ElementType { get; }

Public Overrides ReadOnly Property ElementType As ElementType

Property Value

ElementType

The ElementType of this Element instance.

Overrides

Element.ElementType

FieldType

Gets the field type.

C#
VB.NET

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.

C#
VB.NET

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.

C#
VB.NET

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.

C#
VB.NET

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

ResultInlines

Gets the field result Inlines.

C#
VB.NET

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.

C#
VB.NET

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.

C#
VB.NET

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.

C#
VB.NET

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.

Explicit Interface Implementations

IEnumerable<ElementCollection> IContentElement.get_Content()

Function dfd97gj87thv4l3wnwn2gxqmjbru8d8k   As IEnumerable(Of ElementCollection) Implements IContentElement.get_Content

Returns

IEnumerable<ElementCollection>

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)

Implements

IContentElement

Examples

Update Word Form Controls in C# and VB.NET

Read Word Form Controls in C# and VB.NET

Create Word Form Controls in C# and VB.NET