ImageFieldMergingArgs Class
Provides data for the ImageFieldMerging(ImageFieldMergingArgs) event.
Inheritance Hierarchy

Namespace: Aspose.Words.MailMerging
Assembly: Aspose.Words (in Aspose.Words.dll) Version: 19.9
Syntax
public class ImageFieldMergingArgs : FieldMergingArgsBase

The ImageFieldMergingArgs type exposes the following members.

Properties
  NameDescription
Public propertyCode exampleDocument
Returns the Document object for which the mail merge is performed.
(Inherited from FieldMergingArgsBase.)
Public propertyCode exampleDocumentFieldName
Gets the name of the merge field as specified in the document.
(Inherited from FieldMergingArgsBase.)
Public propertyCode exampleField
Gets the object that represents the current merge field.
(Inherited from FieldMergingArgsBase.)
Public propertyCode exampleFieldName
Gets the name of the merge field in the data source.
(Inherited from FieldMergingArgsBase.)
Public propertyCode exampleFieldValue
Gets the value of the field from the data source.
(Inherited from FieldMergingArgsBase.)
Public propertyCode exampleImage
Specifies the image that the mail merge engine must insert into the document.
Public propertyCode exampleImageFileName
Sets the file name of the image that the mail merge engine must insert into the document.
Public propertyCode exampleImageHeight
Specifies the image height for the image to insert into the document.
Public propertyCode exampleImageStream
Specifies the stream for the mail merge engine to read an image from.
Public propertyCode exampleImageWidth
Specifies the image width for the image to insert into the document.
Public propertyCode exampleRecordIndex
Gets the zero based index of the record that is being merged.
(Inherited from FieldMergingArgsBase.)
Public propertyCode exampleTableName
Gets the name of the data table for the current merge operation or empty string if the name is not available.
(Inherited from FieldMergingArgsBase.)
Methods
  NameDescription
Public methodEquals
Determines whether the specified Object is equal to the current Object.
(Inherited from Object.)
Protected methodFinalize
Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.
(Inherited from Object.)
Public methodGetHashCode
Serves as a hash function for a particular type.
(Inherited from Object.)
Public methodGetType
Gets the type of the current instance.
(Inherited from Object.)
Protected methodMemberwiseClone
Creates a shallow copy of the current Object.
(Inherited from Object.)
Public methodToString
Returns a string that represents the current object.
(Inherited from Object.)
Remarks

This event occurs during mail merge when an image mail merge field is encountered in the document. You can respond to this event to return a file name, stream, or an Image object to the mail merge engine so it is inserted into the document.

There are three properties available ImageFileName, ImageStream and Image to specify where the image must be taken from. Set only one of these properties.

To insert an image mail merge field into a document in Word, select Insert/Field command, then select MergeField and type Image:MyFieldName.

Examples
Shows how to insert images stored in a database BLOB field into a report.
[C#]

Document doc = new Document(MyDir + "MailMerge.MergeImage.doc");

    // Set up the event handler for image fields.
    doc.MailMerge.FieldMergingCallback = new HandleMergeImageFieldFromBlob();

    // Open a database connection.
    string connString = "Provider=Microsoft.ACE.OLEDB.12.0;Data Source=" + DatabaseDir + "Northwind.mdb";
    OleDbConnection conn = new OleDbConnection(connString);
    conn.Open();

    // Open the data reader. It needs to be in the normal mode that reads all record at once.
    OleDbCommand cmd = new OleDbCommand("SELECT * FROM Employees", conn);
    IDataReader dataReader = cmd.ExecuteReader();

    // Perform mail merge.
    doc.MailMerge.ExecuteWithRegions(dataReader, "Employees");

    // Close the database.
    conn.Close();

    doc.Save(ArtifactsDir + "MailMerge.MergeImage.doc");
}

private class HandleMergeImageFieldFromBlob : IFieldMergingCallback
{
    void IFieldMergingCallback.FieldMerging(FieldMergingArgs args)
    {
        // Do nothing.
    }

    /// <summary>
    /// This is called when mail merge engine encounters Image:XXX merge field in the document.
    /// You have a chance to return an Image object, file name or a stream that contains the image.
    /// </summary>
    void IFieldMergingCallback.ImageFieldMerging(ImageFieldMergingArgs e)
    {
        // The field value is a byte array, just cast it and create a stream on it.
        MemoryStream imageStream = new MemoryStream((byte[])e.FieldValue);
        // Now the mail merge engine will retrieve the image from the stream.
        e.ImageStream = imageStream;
    }
}
Examples
Shows how to set the dimensions of merged images.
[C#]

public void MergeFieldImageDimension()
{
    Document doc = new Document();

    // Insert a merge field where images will be placed during the mail merge
    DocumentBuilder builder = new DocumentBuilder(doc);
    builder.InsertField("MERGEFIELD Image:ImageColumn");

    // Create a data table for the mail merge
    // The name of the column that contains our image filenames needs to match the name of our merge field
    System.Data.DataTable dataTable = CreateDataTable("Images", "ImageColumn",
        new string[]
        {
            ImageDir + "Aspose.Words.gif",
            ImageDir + "Watermark.png",
            ImageDir + "dotnet-logo.png"
        });

    doc.MailMerge.FieldMergingCallback = new MergedImageResizer(450, 200, MergeFieldImageDimensionUnit.Point);
    doc.MailMerge.Execute(dataTable);

    doc.UpdateFields();
    doc.Save(ArtifactsDir + "Field.MergeFieldImageDimension.docx");
}

/// <summary>
/// Creates a data table with a single column
/// </summary>
private System.Data.DataTable CreateDataTable(string tableName, string columnName, string[] columnContents)
{
    System.Data.DataTable dataTable = new System.Data.DataTable(tableName);
    dataTable.Columns.Add(new System.Data.DataColumn(columnName));

    foreach (string s in columnContents)
    {
        System.Data.DataRow dataRow = dataTable.NewRow();
        dataRow[0] = s;
        dataTable.Rows.Add(dataRow);
    }

    return dataTable;
}

/// <summary>
/// Sets the size of all mail merged images to one defined width and height 
/// </summary>
private class MergedImageResizer : IFieldMergingCallback
{
    public MergedImageResizer(double imageWidth, double imageHeight, MergeFieldImageDimensionUnit unit)
    {
        mImageWidth = imageWidth;
        mImageHeight = imageHeight;
        mUnit = unit;
    }

    public void FieldMerging(FieldMergingArgs e)
    {
        throw new NotImplementedException();
    }

    public void ImageFieldMerging(ImageFieldMergingArgs args)
    {
        args.ImageFileName = args.FieldValue.ToString();
        args.ImageWidth = new MergeFieldImageDimension(mImageWidth, mUnit);
        args.ImageHeight = new MergeFieldImageDimension(mImageHeight, mUnit);

        Assert.AreEqual(mImageWidth, args.ImageWidth.Value);
        Assert.AreEqual(mUnit, args.ImageWidth.Unit);
        Assert.AreEqual(mImageHeight, args.ImageHeight.Value);
        Assert.AreEqual(mUnit, args.ImageHeight.Unit);
    }

    private readonly double mImageWidth;
    private readonly double mImageHeight;
    private readonly MergeFieldImageDimensionUnit mUnit;
}
See Also