Skip to main content
.NET Framework 4.5.2+

Field Interface

A document field.

Namespace: DevExpress.XtraRichEdit.API.Native

Assembly: DevExpress.RichEdit.v22.1.Core.dll

Declaration

[ComVisible(true)]
public interface Field

The following members return Field objects:

Library Related API Members
WinForms Controls SnapEntity.Field
Office File API Field.Parent
FieldCollection.Create(DocumentPosition, String)
FieldCollection.Create(DocumentRange)

Remarks

Overview

A Field is a placeholder used to insert text and graphics into a document. A field code includes the following elements:

Field Name
The field name. Refer to the following article for a list of all available fields: Field Codes.
Property
Instruction or variable used in a field. This is an optional element.
Switch
An optional parameter that allows you to modify a field result. A switch starts with a backslash followed by a switch argument. A field can have its own set of switches that specify the field’s behavior. You can also use format switches to define formats for numeric, text, date, and time fields. Refer to the following section for a list of supported format switches: Format Switches.

Field Code Structure

A field in the document consists of two ranges—CodeRange and ResultRange. Use the Field.Range property to obtain the total range the field occupies.

Insert and Modify Fields

Fields are stored in the FieldCollection collection. The SubDocument.Fields property allows you to access the field collection. Call the FieldCollection.Create method to insert a new field. 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.BeginUpdateSubDocument.EndUpdate
Header Section.BeginUpdateHeaderSection.EndUpdateHeader
Footer Section.BeginUpdateFooterSection.EndUpdateFooter
Comment Comment.BeginUpdateComment.EndUpdate
Footnote and Endnote Note.BeginUpdateNote.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:

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.OpenXml);
}

Example: Create a Field from a Range

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

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.OpenXml);
}

Example: Modify a Field

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

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();
}

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:

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();
}

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:

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;
}  

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:

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();
        }
    }
}

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:

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); 
    }
}

The following code snippets (auto-collected from DevExpress Examples) contain references to the Field interface.

Note

The algorithm used to collect these code examples remains a work in progress. Accordingly, the links and snippets below may produce inaccurate results. If you encounter an issue with code examples below, please use the feedback form on this page to report the issue.

See Also