RichEditControl.CalculateDocumentVariable Event

Fires when the DOCVARIABLE field is updated.

Namespace: DevExpress.Xpf.RichEdit

Assembly: DevExpress.Xpf.RichEdit.v19.1.dll

Declaration

C#

public event CalculateDocumentVariableEventHandler CalculateDocumentVariable

VB.NET

Public Event CalculateDocumentVariable As CalculateDocumentVariableEventHandler

Event Data

The CalculateDocumentVariable event's data class is CalculateDocumentVariableEventArgs. 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 for the DOCVARIABLE field. 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 MailMerge method call. Handle this event to analyze DOCVARIABLE field switches and arguments, and provide custom content to insert into this field.

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

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

Note

Always provide a check for the e.Arguments[0] value with nested fields (such as {DOCVARIABLE {MERGEFIELD MyDataField_1}}). When the CalculateDocumentVariable event is fired for the first time, e.Arguments[0] contains the <<MyDataField_1>> (the placeholder for the field) since the merge field is not yet calculated. Do not handle the event if the argument is invalid (use comparison and return statements if required) .

This code snippet demonstrates how to handle the RichEditControl.CalculateDocumentVariable event to insert dynamic content into the document. In this example, it is used to get weather report or geo coordinates from Google web service. 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.

Note

A complete sample project is available at https://github.com/DevExpress-Examples/dxrichedit-for-wpf-how-to-use-document-variable-docvariable-fields-e3282.

MainWindow.xaml.cs

void eventHandler_CalculateDocumentVariable(object sender, CalculateDocumentVariableEventArgs e) {
    string location = e.Arguments[0].Value.ToString();

    Console.WriteLine(e.VariableName + " " + location);

    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("Forecast for {0}: \nConditions: {1}\nTemperature (C) :{2}\nHumidity: {3}\nWind: {4}\n",
        //        conditions.City, conditions.Condition, conditions.TempC, conditions.Humidity, conditions.Wind);
        //    break;
        case "Location":
            GeoLocation[] loc = GeoLocation.GeocodeAddress(location);
            e.Value = String.Format(" {0}\nLatitude: {1}\nLongitude: {2}\n",
                loc[0].Address, loc[0].Latitude.ToString(), loc[0].Longitude.ToString());
            break;
    }
    e.Handled = true;
}

MainWindow.xaml.vb

Private Sub eventHandler_CalculateDocumentVariable(ByVal sender As Object, ByVal e As CalculateDocumentVariableEventArgs)
    Dim location As String = e.Arguments(0).Value.ToString()

    Console.WriteLine(e.VariableName & " " & location)

    If (location.Trim() = String.Empty) OrElse (location.Contains("<")) Then
        e.Value = " "
        e.Handled = True
        Return
    End If

    Select Case e.VariableName
        'case "Weather":
        '    Conditions conditions = new Conditions();
        '    conditions = Weather.GetCurrentConditions(location);
        '    e.Value = String.Format("Forecast for {0}: \nConditions: {1}\nTemperature (C) :{2}\nHumidity: {3}\nWind: {4}\n",
        '        conditions.City, conditions.Condition, conditions.TempC, conditions.Humidity, conditions.Wind);
        '    break;
        Case "Location"
            Dim loc() As GeoLocation = GeoLocation.GeocodeAddress(location)
            e.Value = String.Format(" {0}" & Constants.vbLf & "Latitude: {1}" & Constants.vbLf & "Longitude: {2}" & Constants.vbLf, loc(0).Address, loc(0).Latitude.ToString(), loc(0).Longitude.ToString())
    End Select
    e.Handled = True
End Sub

Note

Set the event arguments’ CalculateDocumentVariableEventArgs.Value property to the DocVariableValue.Current value in the CalculateDocumentVariable event handler to save the initial DOCVARIABLE field value.

Related GitHub Examples

The following code snippet (auto-collected from DevExpress Examples) contains a reference to the CalculateDocumentVariable event.

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.

C#

how-to-embed-a-live-chart-into-a-document-using-a-docvariable-field-e3914/CS/RichEdit_InsertChart/MainWindow.xaml#L43

    </dxr:RibbonControl>
    <dxre:RichEditControl Name="richEditControl1" BarManager="{Binding ElementName=barManager1, Mode=OneTime}" Ribbon="{Binding ElementName=ribbonControl1, Mode=OneTime}" CalculateDocumentVariable="richEditControl1_CalculateDocumentVariable" />
</DockPanel>