FieldCollection Interface

A collection of document fields.

Namespace : DevExpress.XtraRichEdit.API.Native

Assembly : DevExpress.RichEdit.v25.2.Core.dll

NuGet Package : DevExpress.RichEdit.Core

Declaration

C#
VB.NET

csharp

[ComVisible(true)]
public interface FieldCollection :
    ReadOnlyFieldCollection,
    ISimpleCollection<Field>,
    IEnumerable<Field>,
    IEnumerable,
    ICollection

<ComVisible(True)>
Public Interface FieldCollection
    Inherits ReadOnlyFieldCollection,
             ISimpleCollection(Of Field),
             IEnumerable(Of Field),
             IEnumerable,
             ICollection

The following members return FieldCollection objects:

SubDocument.Fields

Remarks

Insert and Modify Fields

Call the Create method to create a new Field object. You can add fields to any SubDocument—the main document body, headers, footers, text boxes, comments, footnotes, and endnotes. Use the following API to access the content of these document parts:

Document part	Member
Main document body	SubDocument.BeginUpdate–SubDocument.EndUpdate
Header	Section.BeginUpdateHeader–Section.EndUpdateHeader
Footer	Section.BeginUpdateFooter–Section.EndUpdateFooter
Comment	Comment.BeginUpdate–Comment.EndUpdate
Footnote and Endnote	Note.BeginUpdate–Note.EndUpdate
Text Box	TextBox.Document

Example: Create a Field

The code snippet below uses the SYMBOL field to add a check mark (✔) to the document:

C#
VB.NET

csharp

using DevExpress.XtraRichEdit;
using DevExpress.XtraRichEdit.API.Native;
//...

using (RichEditDocumentServer wordProcessor = new RichEditDocumentServer())
{
    // Access a document.
    Document document = wordProcessor.Document;

    // Start to edit the document.
    document.BeginUpdate();

    // Create the "SYMBOL" field.
    document.Fields.Create(document.Range.Start, "SYMBOL 252 \\f Wingdings \\s 28");

    // Finalize to edit the document.
    document.EndUpdate();

    // Update all fields in the main document body.
    document.Fields.Update();

    // Save the document to the file.
    document.SaveDocument("Result.docx", DocumentFormat.Docx);
}

Imports DevExpress.XtraRichEdit
Imports DevExpress.XtraRichEdit.API.Native
'...

Using wordProcessor As New RichEditDocumentServer()
    ' Access a document.
    Dim document As Document = wordProcessor.Document

    ' Start to edit the document.
    document.BeginUpdate()

    ' Create the "SYMBOL" field.
    document.Fields.Create(document.Range.Start, "SYMBOL 252 \f Wingdings \s 28")

    ' Finalize to edit the document.
    document.EndUpdate()

    ' Update all fields in the main document body.
    document.Fields.Update()

    ' Save the document to the file.
    document.SaveDocument("Result.docx", DocumentFormat.Docx)
End Using

Example: Create a Field from a Range

The code sample below inserts text and converts it to the SYMBOL field.

View Example

FieldActions.cs
FieldActions.vb

csharp

using DevExpress.XtraRichEdit;
using DevExpress.XtraRichEdit.API.Native;

//...
using (RichEditDocumentServer wordProcessor = new RichEditDocumentServer())
{
    Document document = wordProcessor.Document;

    // Start to edit the document.
    document.BeginUpdate();

    // Append text.
    document.AppendText("SYMBOL 0x54 \\f Wingdings \\s 24");

    // Convert inserted text to a field.
    document.Fields.Create(document.Paragraphs[0].Range);

    // Update all fields.
    document.Fields.Update();

    // Finalize to edit the document.
    document.EndUpdate();

    // Save the result
    document.SaveDocument("Result.docx", DocumentFormat.Docx);
}

Imports DevExpress.XtraRichEdit
Imports DevExpress.XtraRichEdit.API.Native

'...
Using wordProcessor As New RichEditDocumentServer()
    Dim document As Document = wordProcessor.Document

    ' Start to edit the document.
    document.BeginUpdate()

    ' Append text.
    document.AppendText("SYMBOL 0x54 \f Wingdings \s 24")

    ' Convert inserted text to a field.
    document.Fields.Create(document.Paragraphs(0).Range)

    ' Update all fields.
    document.Fields.Update()

    ' Finalize to edit the document.
    document.EndUpdate()

    ' Save the result
    document.SaveDocument("Result.docx", DocumentFormat.Docx)
End Using

Example: Modify a Field

The following code snippet specifies a custom date and time format for all DATE fields in the document:

C#
VB.NET

csharp

using DevExpress.XtraRichEdit;
using DevExpress.XtraRichEdit.API.Native;
//...

using (RichEditDocumentServer wordProcessor = new RichEditDocumentServer())
{
    // Access a document.
    Document document = wordProcessor.Document;
    // ...
    // Check all fields in the document.
    for (int i = 0; i < document.Fields.Count; i++)
    {
        // Access a field code.
        string fieldCode = document.GetText(document.Fields[i].CodeRange);
        // Check whether a field code is "DATE".
        if (fieldCode == "DATE")
        {
            // Set the document position to the end of the field code range.
            DocumentPosition position = document.Fields[i].CodeRange.End;
            // Specify a date and time format for the field. 
            document.InsertText(position, @" \@ ""M/d/yyyy HH:mm:ss""");
        }
    }
    // Update all fields in the main document body.
    document.Fields.Update();
}

Imports DevExpress.XtraRichEdit
Imports DevExpress.XtraRichEdit.API.Native
'...

Using wordProcessor As New RichEditDocumentServer()
    ' Access a document.
    Dim document As Document = wordProcessor.Document
    ' ...
    ' Check all fields in the document.
    For i As Integer = 0 To document.Fields.Count - 1
        ' Access a field code.
        Dim fieldCode As String = document.GetText(document.Fields(i).CodeRange)
        ' Check whether a field code is "DATE".
        If fieldCode = "DATE" Then
            ' Set the document position to the end of the field code range.
            Dim position As DocumentPosition = document.Fields(i).CodeRange.End
            ' Specify a date and time format for the field. 
            document.InsertText(position, " \@ ""M/d/yyyy HH:mm:ss""")
        End If
    Next i
    ' Update all fields in the main document body.
    document.Fields.Update()
End Using

Update Fields

Most fields are updated automatically when the document is saved or printed, or during the mail merge operation. Use the following methods to update document fields on demand:

Method	Description
Field.Update	Updates a field.
FieldCollection.Update	Updates all fields in specific parts of the document (main body, text box, header, footer, comment, footnote, and endnote).
Document.UpdateAllFields	Updates all fields in the document.

The code sample below updates all fields in the document:

C#
VB.NET

csharp

using DevExpress.XtraRichEdit;
using DevExpress.XtraRichEdit.API.Native;
//...

using (RichEditDocumentServer wordProcessor = new RichEditDocumentServer())
{
    // Access a document.
    Document document = wordProcessor.Document;
    //...
    // Update all fields in the document.
    document.UpdateAllFields();
}

Imports DevExpress.XtraRichEdit
Imports DevExpress.XtraRichEdit.API.Native
'...

Using wordProcessor As New RichEditDocumentServer()
    ' Access a document.
    Dim document As Document = wordProcessor.Document
    '...
    ' Update all fields in the document.
    document.UpdateAllFields()
End Using

If the field’s Field.Locked property is true , this field is not updated. You can set the FieldOptions.UpdateLockedFields option to UpdateLockedFields.Always to update locked fields.

Suppress Field Updates for Loaded Documents

The Word Processing Document API updates all document fields when it loads a document. You can cancel the DATE, TIME, and DOCVARIABLE field updates. Handle the RichEditDocumentServer.BeforeImport event and define the UpdateFieldOptions options within the event handler to specify whether to update these fields.

The following example demonstrates how to cancel the update of the DATE, TIME, and DOCVARIABLE document fields for all document formats:

C#
VB.NET

csharp

using DevExpress.XtraRichEdit;
using DevExpress.XtraRichEdit.Import;
//...

using (RichEditDocumentServer wordProcessor = new RichEditDocumentServer())
{
    // Handle the BeforeImport event.
    wordProcessor.BeforeImport += WordProcessor_BeforeImport;

    // Load a document from the file.
    wordProcessor.LoadDocument("FirstLook.docx");
}

private static void WordProcessor_BeforeImport(object sender, BeforeImportEventArgs e)
{

    // Cancel the DATE, TIME, and DOCVARIABLE fields' update.
    UpdateFieldOptions updateFieldOptions = ((DocumentImporterOptions)e.Options).UpdateField;
    updateFieldOptions.Date = false;
    updateFieldOptions.Time = false;
    updateFieldOptions.DocVariable = false;
}

Imports DevExpress.XtraRichEdit
Imports DevExpress.XtraRichEdit.Import
'...

Using wordProcessor As New RichEditDocumentServer()

    ' Handle the BeforeImport event.
    AddHandler wordProcessor.BeforeImport, AddressOf WordProcessor_BeforeImport

    ' Load a document from the file.
    wordProcessor.LoadDocument("FirstLook.docx")
End Using

Private Shared Sub WordProcessor_BeforeImport(ByVal sender As Object, ByVal e As BeforeImportEventArgs)

    ' Cancel the DATE, TIME, and DOCVARIABLE fields' update.
    Dim updateFieldOptions As UpdateFieldOptions = CType(e.Options, DocumentImporterOptions).UpdateField
    updateFieldOptions.Date = False
    updateFieldOptions.Time = False
    updateFieldOptions.DocVariable = False
End Sub

Replace Fields with Field Values

You can unlink a field to convert the field result to text or graphics. Unlinked fields cannot be updated. Use the following methods to unlink document fields:

Method	Description
Field.Unlink	Replaces the field with the field value.
FieldCollection.Unlink	Replaces all fields with their values in a specific document part (main body, header, footer, comment, text box, footnote, or endnote).
Document.UnlinkAllFields	Replaces all document fields with field values.

The following example unlinks all fields in text boxes:

C#
VB.NET

csharp

using DevExpress.XtraRichEdit;
using DevExpress.XtraRichEdit.API.Native;
//...

using (RichEditDocumentServer wordProcessor = new RichEditDocumentServer())
{
    // Access a document.
    Document document = wordProcessor.Document;

    // Check all shapes in the document.
    foreach (Shape shape in document.Shapes)
    {
        // Check whether the shape is a text box.
        if (shape.ShapeFormat.HasText)
        {
            // Access text box content.
            SubDocument textBoxDocument = shape.ShapeFormat.TextBox.Document;
            //...
            // Unlink all fields in the text box.
            textBoxDocument.Fields.Unlink();
        }
    }
}

Imports DevExpress.XtraRichEdit
Imports DevExpress.XtraRichEdit.API.Native
'...

Using wordProcessor As New RichEditDocumentServer()
    ' Access a document.
    Dim document As Document = wordProcessor.Document

    ' Check all shapes in the document.
    For Each shape As Shape In document.Shapes

        ' Check whether the shape is a text box.
        If shape.ShapeFormat.HasText Then

            ' Access text box content.
            Dim textBoxDocument As SubDocument = shape.ShapeFormat.TextBox.Document
            '...
            ' Unlink all fields in the text box.
            textBoxDocument.Fields.Unlink()
        End If
    Next shape
End Using

Remove Fields

Call the SubDocument.Delete method and pass the field range to remove the field from the document.

The following example removes all fields from the document:

C#
VB.NET

csharp

using DevExpress.XtraRichEdit;
using DevExpress.XtraRichEdit.API.Native;
//...

using (RichEditDocumentServer wordProcessor = new RichEditDocumentServer())
{
    // Access a document.
    Document document = wordProcessor.Document;
    //...
    // Remove all fields from the collection
    for (int i = document.Fields.Count-1; i >= 0; i--) 
    {
        document.Delete(document.Fields[i].Range); 
    }
}

Imports DevExpress.XtraRichEdit
Imports DevExpress.XtraRichEdit.API.Native
'...

Using wordProcessor As New RichEditDocumentServer()
    ' Access a document.
    Dim document As Document = wordProcessor.Document
    '...
    ' Remove all fields from the collection
    For i As Integer = document.Fields.Count-1 To 0 Step -1
      document.Delete(document.Fields(i).Range)
    Next i
End Using

FieldCollection Interface

FieldCollection Interface

Declaration

Related API Members

Remarks

Insert and Modify Fields

Example: Create a Field

Example: Create a Field from a Range

Example: Modify a Field

Update Fields

Suppress Field Updates for Loaded Documents

Replace Fields with Field Values

Remove Fields