GemBox.Document
  • Overview
  • Examples
  • Free version
  • Support
  • Pricelist

    Show / Hide Table of Contents

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

    IsLocked

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

    • C#
    • VB.NET
    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.

    • C#
    • VB.NET
    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.

    • 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:

    • Author
    • Comments
    • Compare
    • Date
    • DocProperty
    • DocVariable
    • If
    • FileName
    • FormCheckBox
    • FormDropDown
    • Formula
    • IncludePicture
    • Keywords
    • LastSavedBy
    • MacroButton
    • PrintDate
    • SaveDate
    • Set
    • Symbol
    • Subject
    • Time
    • Title

    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

    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
    Back to top

    Facebook • Twitter • LinkedIn

    © GemBox Ltd. — All rights reserved.