SnapControl.SnapMailMergeRecordStarted Event

Occurs before the data field merging starts.

Namespace: DevExpress.Snap

Assembly: DevExpress.Snap.v20.1.dll


public event SnapMailMergeRecordStartedEventHandler SnapMailMergeRecordStarted
Public Event SnapMailMergeRecordStarted As SnapMailMergeRecordStartedEventHandler

Event Data

The SnapMailMergeRecordStarted event's data class is SnapMailMergeRecordStartedEventArgs. The following properties provide information specific to this event:

Property Description
Cancel Gets or sets a value indicating whether the event should be canceled. Inherited from CancelEventArgs.
Document Returns the document that is being merged.
RecordDocument Provides access to the document created for a single record before the fields are processed.
RecordIndex Returns the data record index.


Handle the SnapMailMergeRecordStarted event to perform any actions before the process of field merging starts. For example, you can access and modify the data source collection of a single record document using the SnapDocument.DataSources property of the SnapDocument object accessed via the SnapMailMergeRecordStartedEventArgs.RecordDocument property. Take special note that you are unable to delete or modify the main data source being used for the mail-merge process (i.e., the data source assigned to the DataSource and DataSourceName properties of the SnapMailMergeVisualOptions object). In this case, an InvalidOperationException is thrown.

Note also that when a mail merge is performed in the user interface, the SnapMailMergeRecordStarted event can be raised asynchronously, requiring use of the SnapControl's InvokeRequired property in the event handler to determine if it is necessary to call the SnapControl.Invoke method to execute a delegate in a thread that owns the control.

void snapControl1_SnapMailMergeActiveSnapMailMergeRecordStarted(object sender, SnapMailMergeRecordStartedEventArgs e)
    Action d = delegate {
        // Add a method to handle the event.
    if (snapControl1.InvokeRequired)


This code snippet affects the SNIMAGE field bound to the Picture data field, only for the data record with index = 3. The code enlarges an image two times.

This can be accomplished by iterating over the SubDocument.Fields collection and using the ISnapFieldOwner.ParseField method to find the SnapImage object.

Another way is to perform a text search and replace in the field code range. For this, the document must display field codes (the Field.ShowCodes is true for the required field).

static void server_SnapMailMergeRecordStarted(object sender, SnapMailMergeRecordStartedEventArgs e)
    if (e.RecordIndex == 3) {
        for (int i = 0; i < e.RecordDocument.Fields.Count; i++)                {
            DevExpress.XtraRichEdit.API.Native.Field item = e.RecordDocument.Fields[i];
            SnapImage snImage = e.RecordDocument.ParseField(item) as SnapImage;
            if (snImage != null)
                if (snImage.DataFieldName == "Picture")
                    snImage.ScaleX = snImage.ScaleX * 2;
                    snImage.ScaleY = snImage.ScaleY * 2;

        // Another code snippet for the same result:
        //e.RecordDocument.Fields[2].ShowCodes = true;
        //e.RecordDocument.Replace(e.RecordDocument.Fields[2].CodeRange, @"SNIMAGE Picture \sy 20000 \sx 20000");
See Also