[Expand]General Information
[Collapse]WinForms Controls
 [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]Property Grid
  [Expand]Pivot Grid
  [Expand]Tree List
  [Expand]Chart Control
  [Expand]Map Control
  [Collapse]Rich Text Editor
   [Expand]Product Information
    Product Class Structure
    Supported Formats
   [Expand]Getting Started
   [Expand]RichEditControl Document
    [Collapse]Field Codes
    [Expand]Format Switches
    Text Formatting
    Import and Export
   [Expand]Page Layout
    Spell Checking
    Mail Merge
    Restrictions and Protection
    Syntax Highlighting
    Traversing the Document
   [Expand]Visual Elements
    Keyboard Shortcuts
    HTML Tag Support
  [Expand]Spell Checker
  [Expand]Form Layout Managers
  [Expand]Navigation Controls
  [Expand]PDF Viewer
  [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]Office File API
[Expand]Report and Dashboard Server
[Expand]eXpressApp Framework
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation



Mixed field

{ DOCVARIABLE "variable name" "argument1" "argument 2"... }

Expanded Overview

Inserts the value of a document variable specified by a text in the field argument. Document variables are contained in the DocumentVariableCollection collection object, accessible using the Document.Variables property.

You can handle the Document.CalculateDocumentVariable event which is fired before a field is updated. The CalculateDocumentVariableEventArgs.Arguments property provides access to a collection of arguments contained within the field, so that you can analyze them and calculate a proper value for the CalculateDocumentVariableEventArgs.Value property. That value substitutes the previous value of the field.

If the Document.CalculateDocumentVariable event is not handled, it does not occur. In this situation, the field update replaces its former value with the value of the corresponding document variable. If a variable with that name is not found, a field result is set to an empty string.


When the DOCVARIABLE field is updated, its previous value is lost. To prevent this, handle the Document.CalculateDocumentVariable event and set the CalculateDocumentVariableEventArgs.Value property of event arguments to the DocVariableValue.Current value.

You can specify whether the DOCVARIABLE fields are updated before printing or copying a range to the Clipboard. Use the FieldOptions.UpdateDocVariablesBeforeCopy, Document.UpdateDocVariablesBeforePrint or the FieldOptions.UpdateDocVariablesBeforePrint option.

Expanded Locking the Field

If a field is locked (the Field.Locked property is true), the field cannot be updated by the Field.Update or FieldCollection.Update methods and by executing UI commands. The Document.CalculateDocumentVariable event is not raised for a locked field and it retains its previous value. However, you can set the FieldOptions.UpdateLockedFields option to change default actions for locked fields.

Expanded Simple Example of Use

You can return a text or the entire document as a document variable. Thus, updating a DOCVARIABLE field and handling the Document.CalculateDocumentVariable event is a useful method of constructing complex documents.

Consider mail merge activity. When the RichEditControl.MailMerge method is called, all fields are updated. A common task is to evaluate DOCVARIABLE fields in a document depending on the variable name and argument and then substitute fields with their values.

Show Me

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

This code snippet demonstrates how to handle the RichEditControl.CalculateDocumentVariable event to insert custom content into the document. In this example, it is used to get weather conditions. A variable name specified in the DOCVARIABLE field indicates a choice between location and weather, while the location itself is specified by the field argument.

Expanded Master-Detail Report

A combination of the Mail Merge feature with the DOCVARIABLE field and RichEditDocumentServer instances enables you to create a master-detail report. Although the Snap Reporting performs this task with less effort, master-detail reporting is a good illustration of DOCVARIABLE versatility. For more information, review the following example.

Show Me

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

Expanded See Also

Is this topic helpful?​​​​​​​