Field Class
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, IContentElementPublic 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.
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.
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.
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 CharacterFormatProperty Value
The character format.
Document
Gets the owner document.
public override DocumentModel Document { get; }Public Overrides ReadOnly Property Document As DocumentModelProperty Value
The owner document.
Overrides
ElementType
Gets the ElementType of this Element instance.
public override ElementType ElementType { get; }Public Overrides ReadOnly Property ElementType As ElementTypeProperty Value
The ElementType of this Element instance.
Overrides
FieldType
Gets the field type.
Property Value
The field type.
FormData
Gets the form related data associated with the parent form field or null if parent field is not form field.
Property Value
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 InlineCollectionProperty Value
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.
Property Value
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.
Property Value
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
Property Value
ResultInlines
Gets the field result Inlines.
public InlineCollection ResultInlines { get; }Public ReadOnly Property ResultInlines As InlineCollectionProperty Value
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.
Parameters
cloneResult- Boolean
true to clone field result; otherwise false.
Returns
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.
Returns
The field instruction text if InstructionInlines contains only Run, SpecialCharacter, InlineContentControl elements and bookmarks; otherwise Empty.
Update()
Updates the ResultInlines of the current Field.
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
- DisplayBarcode
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) |