Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[Expand]General Information
[Collapse]WinForms Controls
  Prerequisites
 [Expand]What's Installed
 [Expand]Build an Application
 [Collapse]Controls and Libraries
  [Expand]Forms and User Controls
  [Expand]Messages, Notifications and Dialogs
  [Expand]Editors and Simple Controls
  [Expand]Ribbon, Bars and Menu
  [Expand]Application UI Manager
  [Expand]Docking Library
  [Expand]Data Grid
  [Expand]Vertical Grid
  [Expand]Pivot Grid
  [Expand]Tree List
  [Expand]Chart Control
  [Expand]Diagrams
  [Expand]Gauges
  [Expand]Map Control
  [Expand]Scheduler
  [Expand]Spreadsheet
  [Collapse]Rich Text Editor
   [Expand]Product Information
    Product Class Structure
   [Expand]Getting Started
   [Expand]RichEditControl Document
   [Collapse]Fields
    [Expand]Field Codes
    [Expand]Format Switches
    Text Formatting
    Import and Export
   [Expand]Page Layout
    Printing
    Spell Checking
    AutoCorrect
    Mail Merge
    Restrictions and Protection
    Syntax Highlighting
    Traversing the Document
   [Expand]Visual Elements
    Services
    Events
    Commands
   [Expand]Member Tables
    Keyboard Shortcuts
    HTML Tag Interpretation
   [Expand]Examples
  [Expand]Spell Checker
  [Expand]Form Layout Managers
  [Expand]Navigation Controls
  [Expand]Printing-Exporting
  [Expand]PDF Viewer
   Reporting
  [Expand]Snap
  [Expand]TreeMap Control
 [Expand]Common Features
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Expand]Reporting
[Expand]Report Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]CodeRush
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Fields

This topic consists the following sections:

Expanded Overview

The Field is a set of codes that instructs the RichEditControl to insert text or graphics into a document automatically. The field code syntax is illustrated and described below.

  • Field Name - the name of the current field. Refer to the Field Codes section for a list of all available fields.
  • Property - instruction/variable used in a particular field. This is an optional element.
  • Switch - an additional parameter that offers more information. This is an optional element. Refer to the Format Switches section for a list of supported format switches.

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

The RichEditControl supports the following field types:

  1. Non-MailMerge
    Regular fields used to insert a simple data, such as DATE, TIME or PAGE. The Non-MailMerge field results are shown after the update.

  2. MailMerge
    Fields used in the Mail Merge process. They get a value only if there is a mail merge data source bound to the RichEditControl. In the resulting document, MailMerge fields are evaluated and substituted with the resulting values.

  3. Mixed
    Fields which do not require a data source to get its value, such as INCLUDEPICTURE and CREATEDATE. They are substituted with the resulting values during mail merge.

Expanded Insert and Modify Fields

Members from the table below allow you to insert and modify the field programmatically.

Member Description
SubDocument.BeginUpdate Opens the document for editing.
FieldCollection.Create Creates a new Field object.
SubDocument.Fields Provides access to the collection of fields in the current document.
Field.Range Gets the document range occupied by the field.
Field.CodeRange Gets the range containing the field codes.
Field.ResultRange Gets the range containing the field result.
SubDocument.InsertText Inserts the specified text at the specified position.
SubDocument.EndUpdate Finalizes the modification.

Show Me

A complete sample project is available in the DevExpress Code Examples database at http://www.devexpress.com/example=E5219.

Tip

The header and footer in the RichEditCotnrol document do not belong to the main document body. Use the Section.BeginUpdateHeader - Section.EndUpdateHeader or Section.BeginUpdateFooter - Section.EndUpdateFooter paired methods to obtain the header or footer. Refer to the How to: Create and Modify Header topic for details.

Expanded Update Fields

Most fields are updated automatically when the document is saved or printed, or during the mail merge operation. Use the Field.Update method to update the field on demand. Specify the DocumentImporterOptions.UpdateField property to set what document fields should be updated automatically when loading the document. Use the richEditControl.Options.Import.DocumentFormat.UpdateField notation (where DocumentFormat is one of the RichTextEditDocumentImportOptions properties) to access this property.
Set the field's Field.Locked property to true to prevent a specific field from being updated. Use the FieldOptions.UpdateLockedFields option to allow updating locked fields.

The DOCVARIABLE field is not updated during mail merge or document insertion. Handle the RichEditControl.CalculateDocumentVariable event to update the DOCVARIABLE fields' values.

The RichEditControl.CalculateDocumentVariable event does not occur for a locked DOCVARIABLE field, and the field value remains unchanged. Set the FieldOptions.UpdateLockedFields option to the UpdateLockedFields.DocVariableOnly value to update DOCVARIABLE fields.

Show Me

A complete sample project is available in the DevExpress Code Examples database at http://www.devexpress.com/example=E3099.

Expanded Field Options

Use the Field.ShowCodes property to change the target field's display mode. You can also use ShowAllFieldCodesCommand or ShowAllFieldResultsCommand commands to change the display mode of all document fields.

Show Me

A complete sample project is available in the DevExpress Code Examples database at http://www.devexpress.com/example=E5219.

This code snippet displays field codes for all fields in the main document body.
The fields containing in the header or footer belong to a different FieldCollection. Use the Section.BeginUpdateHeader- Section.EndUpdateHeader or Section.BeginUpdateFooter - Section.EndUpdateFooter paired methods to retrieve the header or footer document.

Use the RichEditControlOptionsBase.Fields to specify how RichEditControl should process and display document fields, as shown in the code snippet below:

Set the DocumentCapabilitiesOptions.Fields property to DocumentCapability.Hidden or DocumentCapability.Disabled to restrict inserting fields to the document.

Expanded Operate Fields in the User Interface

To simplify many common tasks when working with fields, the Rich Editor UI provides the following commands and shortcuts:

Task

UI Command / Shortcut Key

Insert a field Press CTRL+F9.
Show field codes Press ALT+F9 or click the Show All Field Codes button in the Mail Merge Ribbon page or Bar group.
Update field values Select a range containing fields and press F9.
Show spaces and formatting marks Press CTRL+SHIFT+8.

End-users can update or toggle the code of the document field from the context menu or by using the Mail Merge ribbon tab. Refer to the How to: Create a Simple Word Processor with a Ribbon UI topic for details on how to provide a Ribbon UI for the RichEditControl.

MERGEFIELD Display Modes

When the Show All Field Results button is clicked (or the ShowAllFieldResultsCommand is executed), the MERGEFIELD field is shown as a placeholder:

End-users can click View Merged Data to display the MERGEFIELD code result:

Set the RichEditMailMergeOptions.ViewMergedData to true or execute the ToggleViewMergedDataCommand command to achieve this task programmatically.

Expanded See Also

How would you rate this topic?​​​​​​​