.NET Framework 4.5.2+
.NET Framework 4.5.2+
.NET Standard 2.0+
.NET Core 3.0+

Document.CalculateDocumentVariable Event

Fires when the DOCVARIABLE field is updated.

Namespace: DevExpress.XtraRichEdit.API.Native

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

Declaration

event CalculateDocumentVariableEventHandler CalculateDocumentVariable
Event CalculateDocumentVariable As CalculateDocumentVariableEventHandler
event CalculateDocumentVariableEventHandler CalculateDocumentVariable
Event CalculateDocumentVariable As CalculateDocumentVariableEventHandler
event CalculateDocumentVariableEventHandler CalculateDocumentVariable
Event CalculateDocumentVariable As CalculateDocumentVariableEventHandler

Event Data

The CalculateDocumentVariable event handler receives an argument of the CalculateDocumentVariableEventArgs type. The following properties provide information specific to this event.

Property Description
Arguments Provides access to a collection of arguments within the DOCVARIABLE field.
FieldLocked Gets or sets a locked attribute to the field for which the event occurs.
Handled Gets or sets whether the default action is required.
KeepLastParagraph Gets or sets whether the last paragraph of the inserted document is kept in the resulting document.
PreserveInsertedContentFormatting Gets or sets whether to insert an additional hidden paragraph so that the inserted content is not formatted with the DOCVARIABLE field's paragraph formatting.
Value Gets or sets the value of the DOCVARIABLE field that fired the event.
VariableName Gets the name of the document variable to which the DOCVARIABLE field refers.

Remarks

The CalculateDocumentVariable event is fired when the DOCVARIABLE value is calculated. The event is fired when a field is updated (using UI commands, Field.Update or FieldCollection.Update methods), or during the Mail Merge on the RichEditControl.MailMerge method call. Handle this event to analyze DOCVARIABLE field switches and arguments, and provide custom content to insert into this field.

Assign a special DocVariableValue.Current value to the CalculateDocumentVariableEventArgs.Value property and set e.Handled to true to retain the existing DOCVARIABLE value.

You can specify the FieldOptions.UpdateLockedFields property to raise the event for locked DOCVARIABLE fields.

You can lock/unlock the field within the CalculateDocumentVariable handler using the CalculateDocumentVariableEventArgs.FieldLocked property. Set e.Handled to true to apply changes.

Examples

Note

A complete code sample project is available at How to use document variable (DOCVARIABLE) fields.

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

XtraRichEdit_CalculateDocumentVariable_Example

 private static void Document_CalculateDocumentVariable(object sender, CalculateDocumentVariableEventArgs e)
        {
            if (e.Arguments.Count > 0)
            {
                string location = e.Arguments[0].Value.ToString();
                if ((location.Trim() == String.Empty) || (location.Contains("<")))
                {
                    e.Value = " ";
                    e.Handled = true;
                    return;
                }
                switch (e.VariableName)
                {
                    case "Weather":
                        Conditions conditions = new Conditions();
                        conditions = Weather.GetCurrentConditions(location);
                        e.Value = String.Format("Weather for {0}: \nConditions: {1}\nTemperature (C) :{2}\nHumidity: {3}\nWind: {4}\n",
                            location, conditions.Condition, conditions.TempC, conditions.Humidity, conditions.Wind);
                        break;
                    case "LOCATION":
                        if (location == "DO NOT CHANGE!") e.Value = DocVariableValue.Current;
                        break;
                    default:
                        e.Value = "LOCKED FIELD UPDATED";
                        break;
                }
            }
            else
            {
                e.Value = "LOCKED FIELD UPDATED";
            }
            e.Handled = true;
        }
See Also