SnapControl.SnapMailMergeRecordStarted Event

Occurs before the data field merging starts.

Namespace: DevExpress.Snap

Assembly: DevExpress.Snap.v19.1.dll

Declaration

C#

public event SnapMailMergeRecordStartedEventHandler SnapMailMergeRecordStarted

VB.NET

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.

Remarks

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.

C#

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

VB.NET

Private Sub snapControl1_SnapMailMergeRecordStarted(ByVal sender As Object, ByVal e As SnapMailMergeRecordStartedEventArgs)
    Dim d As Action = Sub()
        ' Add a method to handle the event.
    End Sub
    If snapControl1.InvokeRequired Then
        snapControl1.Invoke(d)
    Else
        d()
    End If
End Sub

Example

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).

Note

A complete sample project is available at https://github.com/DevExpress-Examples/how-to-automatically-create-mail-merge-documents-using-the-snap-document-server-e5078

Program.cs

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.BeginUpdate();
                    snImage.ScaleX = snImage.ScaleX * 2;
                    snImage.ScaleY = snImage.ScaleY * 2;
                    snImage.EndUpdate();
                    item.Update();
                }
            }
        }
        e.RecordDocument.EndUpdate();

        // 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");
        //e.RecordDocument.Fields[2].Update();
    }
}

Program.vb

Private Shared Sub server_SnapMailMergeRecordStarted(ByVal sender As Object, ByVal e As SnapMailMergeRecordStartedEventArgs)
    If e.RecordIndex = 3 Then
        For i As Integer = 0 To e.RecordDocument.Fields.Count - 1
            Dim item As DevExpress.XtraRichEdit.API.Native.Field = e.RecordDocument.Fields(i)
            Dim snImage As SnapImage = TryCast(e.RecordDocument.ParseField(item), SnapImage)
            If snImage IsNot Nothing Then
                If snImage.DataFieldName = "Picture" Then
                    snImage.BeginUpdate()
                    snImage.ImageSizeMode = DevExpress.XtraPrinting.ImageSizeMode.Tile
                    snImage.ScaleX = snImage.ScaleX * 2
                    snImage.ScaleY = snImage.ScaleY * 2
                    snImage.EndUpdate()
                    item.Update()
                End If
            End If
        Next i
        e.RecordDocument.EndUpdate()

        ' 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");
        'e.RecordDocument.Fields[2].Update();
    End If
End Sub