ReplaceImage(String,Int32,Boolean) Method

In This Topic

Replaces a destination image, specified by its resource name, located in the currently loaded PDF document, by the newly added source image, specified by its unique image identifier. You can obtain this identifier, for example, using the ExtractPageImage method or using methods of the GdPictureImaging class when creating the source image as an object of the type GdPictureImage. If the destination image is used either elsewhere on the same page or on another page, it is replaced by the source image on all places within the current document.

Syntax

Visual Basic
C#
Delphi
JScript
Managed Extensions for C++
C++/CLI

'Declaration
 
Public Overloads Function ReplaceImage( _
   ByVal ImageResName As String, _
   ByVal ImageID As Integer, _
   ByVal ImageMask As Boolean _
) As GdPictureStatus

public GdPictureStatus ReplaceImage( 
   string ImageResName,
   int ImageID,
   bool ImageMask
)

public function ReplaceImage( 
    ImageResName: String;
    ImageID: Integer;
    ImageMask: Boolean
): GdPictureStatus;

public function ReplaceImage( 
   ImageResName : String,
   ImageID : int,
   ImageMask : boolean
) : GdPictureStatus;

public: GdPictureStatus ReplaceImage( 
   string* ImageResName,
   int ImageID,
   bool ImageMask
)

public:
GdPictureStatus ReplaceImage( 
   String^ ImageResName,
   int ImageID,
   bool ImageMask
)

Parameters

ImageResName: The image resource name of the destination image, previously returned by the AddImageFrom...(), AddJpegImageFrom...() or GetPageImageResName methods.
ImageID: The unique image identifier of the source image refering to an object of the type GdPictureImage. You need to add this image as a resource into the currently loaded PDF document, for example, using methods of the GdPictureImaging class, whose returned value is the unique image identifier.
ImageMask: Applicable only for 1 bit per pixel images. Indicates, whether the source image shall be treated as an image mask (or stencil mask). The commonly recommended default value is false.
Please refer to the Remarks section below or go over the GetPageImageMaskMode method directly for further information on how to use this parameter.

Return Value

A member of the GdPictureStatus enumeration. If the method has been successfully followed, then the return value is GdPictureStatus.OK.

We strongly recommend always checking this status first.

Remarks

This method is only allowed for use with non-encrypted documents.

Just to inform you, that you can check the current image masking using the GetPageImageMaskMode method to apply the ImageMask parameter properly. If the value returned by the above mentioned method is PdfMaskTypeNone or PdfMaskTypeUnknown, set the ImageMask parameter to false. Otherwise you can set it to true.

Example

How to replace all images in the PDF document after converting them into 1 bit per pixel (black and white) images.

VB.NET
C#

Dim caption As String = "Example: ReplaceImage"
Dim gdpicturePDF As New GdPicturePDF()
If gdpicturePDF.LoadFromFile("test.pdf", False) = GdPictureStatus.OK Then
    Dim imageCount As Integer = 0, imageID As Integer = 0, bitDepth As Integer = 0
    Dim message As String = "", imageResName As String = ""
    Dim maskMode As PdfImageMaskType = PdfImageMaskType.PdfMaskTypeUnknown
    Dim mask As Boolean = False
    Dim oImage As New GdPictureImaging()
    Dim pageCount As Integer = gdpicturePDF.GetPageCount()
    Dim status As GdPictureStatus = gdpicturePDF.GetStat()
    If (status = GdPictureStatus.OK) AndAlso (pageCount > 0) Then
        For i As Integer = 1 To pageCount
            status = gdpicturePDF.SelectPage(i)
            If status = GdPictureStatus.OK Then
                message = message + "Page nr." + i.ToString() + vbCrLf
                imageCount = gdpicturePDF.GetPageImageCount()
                status = gdpicturePDF.GetStat()
                If (status = GdPictureStatus.OK) AndAlso (imageCount > 0) Then
                    For j As Integer = 0 To imageCount - 1
                        imageResName = gdpicturePDF.GetPageImageResName(j)
                        status = gdpicturePDF.GetStat()
                        If status = GdPictureStatus.OK Then
                            imageID = gdpicturePDF.ExtractPageImage(j + 1)
                            status = gdpicturePDF.GetStat()
                            If status = GdPictureStatus.OK Then
                                bitDepth = oImage.GetBitDepth(imageID)
                                status = oImage.GetStat()
                                If (status = GdPictureStatus.OK) AndAlso
                                   (oImage.GetBitDepth(imageID) > 1) AndAlso
                                   (oImage.ConvertTo1Bpp(imageID) = GdPictureStatus.OK) Then
                                    maskMode = gdpicturePDF.GetPageImageMaskMode(j)
                                    mask = ((maskMode <> PdfImageMaskType.PdfMaskTypeNone) AndAlso (maskMode <> PdfImageMaskType.PdfMaskTypeUnknown))
                                    status = gdpicturePDF.ReplaceImage(imageResName, imageID, mask)
                                    If status = GdPictureStatus.OK Then
                                        message = message + "The image named as " + imageResName + " has been successfully replaced." + vbCrLf
                                    Else
                                        message = message + "The ReplaceImage() method has failed for the image numbered as " + (j + 1).ToString() + " with the status: " + status.ToString() + vbCrLf
                                    End If
                                Else
                                    message = message + "The image numbered as " + (j + 1).ToString() + " has not been converted and replaced." + vbCrLf
                                End If
                            Else
                                message = message + "The ExtractPageImage() method has failed for the image numbered as " + (j + 1).ToString() + " with the status: " + status.ToString() + vbCrLf
                            End If
                            'The extracted image need to be released.
                            oImage.ReleaseGdPictureImage(imageID)
                        Else
                            message = message + "The GetPageImageResName() method has failed for the image indexed as " + j.ToString() + " with the status: " + status.ToString() + vbCrLf
                        End If
                    Next
                Else
                    If status = GdPictureStatus.OK Then
                        message = message + "This page doesn't contain any image." + vbCrLf
                    Else
                        message = message + "The GetPageImageCount() method has failed with the status: " + status.ToString() + vbCrLf
                    End If
                End If
            Else
                message = message + "The SelectPage() method has failed with the status: " + status.ToString() + vbCrLf
            End If
        Next
        'It is recommended to pack the document in such cases.
        If gdpicturePDF.SaveToFile("test_ReplaceImage.pdf", True) = GdPictureStatus.OK Then
            message = message + "The file has been saved successfully."
        Else
            message = message + "The file can't be saved. Status: " + gdpicturePDF.GetStat().ToString()
        End If
        MessageBox.Show(message, caption)
    Else
        If status = GdPictureStatus.OK Then
            MessageBox.Show("This file doesn't contain any page.", caption)
        Else
            MessageBox.Show("The GetPageCount() method has failed with the status: " + status.ToString(), caption)
        End If
    End If
    oImage.Dispose()
Else
    MessageBox.Show("The file can't be loaded.", caption)
End If
gdpicturePDF.Dispose()

string caption = "Example: ReplaceImage";
GdPicturePDF gdpicturePDF = new GdPicturePDF();
if (gdpicturePDF.LoadFromFile("test.pdf", false) == GdPictureStatus.OK)
{
    int imageCount = 0, imageID = 0, bitDepth = 0;
    string message = "", imageResName = "";
    PdfImageMaskType maskMode = PdfImageMaskType.PdfMaskTypeUnknown;
    bool mask = false;
    GdPictureImaging oImage = new GdPictureImaging();
    int pageCount = gdpicturePDF.GetPageCount();
    GdPictureStatus status = gdpicturePDF.GetStat();
    if ((status == GdPictureStatus.OK) && (pageCount > 0))
    {
        for (int i = 1; i <= pageCount; i++)
        {
            status = gdpicturePDF.SelectPage(i);
            if (status == GdPictureStatus.OK)
            {
                message = message + "Page nr." + i.ToString() + "\n";
                imageCount = gdpicturePDF.GetPageImageCount();
                status = gdpicturePDF.GetStat();
                if ((status == GdPictureStatus.OK) && (imageCount > 0))
                {
                    for (int j = 0; j < imageCount; j++)
                    {
                        imageResName = gdpicturePDF.GetPageImageResName(j);
                        status = gdpicturePDF.GetStat();
                        if (status == GdPictureStatus.OK)
                        {
                            imageID = gdpicturePDF.ExtractPageImage(j+1);
                            status = gdpicturePDF.GetStat();
                            if (status == GdPictureStatus.OK)
                            {
                                bitDepth = oImage.GetBitDepth(imageID);
                                status = oImage.GetStat();
                                if ((status == GdPictureStatus.OK) &&
                                    (oImage.GetBitDepth(imageID) > 1) &&
                                    (oImage.ConvertTo1Bpp(imageID) == GdPictureStatus.OK))
                                {
                                    maskMode = gdpicturePDF.GetPageImageMaskMode(j);
                                    mask = ((maskMode != PdfImageMaskType.PdfMaskTypeNone) && (maskMode != PdfImageMaskType.PdfMaskTypeUnknown));
                                    status = gdpicturePDF.ReplaceImage(imageResName, imageID, mask);
                                    if (status == GdPictureStatus.OK)
                                        message = message + "The image named as " + imageResName + " has been successfully replaced.\n";
                                    else
                                        message = message + "The ReplaceImage() method has failed for the image numbered as " + (j + 1).ToString() + " with the status: " + status.ToString() + "\n";
                                }
                                else
                                    message = message + "The image numbered as " + (j + 1).ToString() + " has not been converted and replaced.\n";
                            }
                            else
                                message = message + "The ExtractPageImage() method has failed for the image numbered as " + (j+1).ToString() + " with the status: " + status.ToString() + "\n";
                            //The extracted image need to be released.
                            oImage.ReleaseGdPictureImage(imageID);
                        }
                        else
                            message = message + "The GetPageImageResName() method has failed for the image indexed as " + j.ToString() + " with the status: " + status.ToString() + "\n";
                    }
                }
                else
                {
                    if (status == GdPictureStatus.OK)
                        message = message + "This page doesn't contain any image.\n";
                    else
                        message = message + "The GetPageImageCount() method has failed with the status: " + status.ToString() + "\n";
                }
            }
            else
                message = message + "The SelectPage() method has failed with the status: " + status.ToString() + "\n";
        }
        //It is recommended to pack the document in such cases.
        if (gdpicturePDF.SaveToFile("test_ReplaceImage.pdf", true) == GdPictureStatus.OK)
            message = message + "The file has been saved successfully.";
        else
            message = message + "The file can't be saved. Status: " + gdpicturePDF.GetStat().ToString();
        MessageBox.Show(message, caption);
    }
    else
    {
        if (status == GdPictureStatus.OK)
            MessageBox.Show("This file doesn't contain any page.", caption);
        else
            MessageBox.Show("The GetPageCount() method has failed with the status: " + status.ToString(), caption);
    }
    oImage.Dispose();
}
else
    MessageBox.Show("The file can't be loaded.", caption);
gdpicturePDF.Dispose();

Reference

GdPicturePDF Class
GdPicturePDF Members
Overload List
GetPageImageCount Method
GetPageImageResName Method
GetPageImageMaskMode Method
ExtractPageImage Method
GetPageCount Method
SelectPage Method
LoadFromFile Method
SaveToFile(String) Method