ImageGear .NET allows you to copy, cut, and paste all or part of an image to and from the Windows clipboard. The following sections explain how to:

Copy or Cut to the Clipboard

You can copy or cut all or part of an ImGearRasterPage instance to the clipboard:

• To copy image data, call ImGearRasterPage.CopyToClipboard.
• To cut image data replacing it with a specified fill color, call ImGearRasterPage.CutToClipboard. Note that a solid RGB fill color is required when calling cut. If the actual color space of the image is not RGB, ImageGear will automatically use the closest possible match.
• To limit a copy or cut operation to only a portion of an ImGearRasterPage instance, first set the ImGearRasterPage.ROI property (which specifies the active region of interest). Note that a region of interest can be either rectangular (using ImGearROIRectangle) or non-rectangular (using ImGearROIMask).
  When using an ImGearROIMask to set the non-rectangular region of interest, ImageGear does not actually apply the mask before copying or cutting to the clipboard. Instead, both the mask and underlying image data are copied to the clipboard using a proprietary format. As long as this clipboard data is retrieved using the static ImGearRasterPage.GetFromClipboard method, the returned ImGearRasterPage instance will contain both the rectangular image data and a matching non-rectangular mask (as an ImGearRasterPage.ROI property). However, if the data from the Windows clipboard is pasted into a third-party application, the mask will not be honored. Instead, the entire rectangular region beneath the bounding box, defined by the mask, will be pasted.

Check the Contents of the Clipboard

You can check whether the clipboard currently contains image data that is usable by ImageGear via the ImGearRasterPage.CanGetFromClipboard property. We recommend you always check that this property returns true before calling ImGearRasterPage.GetFromClipboard.

Paste from the Clipboard

To get an image from the clipboard as a new ImGearRasterPage instance, call the static ImGearRasterPage.GetFromClipboard method. If the clipboard contains valid image data, a new ImGearRasterPage instance will be returned.

If the clipboard contains data previously copied from an ImGearRasterPage instance that happened to contain a non-rectangular region of interest, then the new ImGearRasterPage instance returned from the clipboard will contain a matching non-rectangular region of interest (the ImGearRasterPage.ROI property will contain an ImGearROIMask instance that matches the mask originally copied to the clipboard).

ImageGear does not provide a special method for pasting the clipboard image into a pre-existing ImGearRasterPage. However, this can be easily achieved using the ImGearRasterProcessing.Merge method.

The following example includes code to handle mismatched color spaces and channel depths:

ImGearRasterPage page = ImGearRasterPage.GetFromClipboard();
if (page != null)
{
    ImGearRasterPage currentPage = this.imGearPage as ImGearRasterPage;
    if (currentPage != null)
    {
        if (!currentPage.DIB.ColorSpace.Equals(page.DIB.ColorSpace))
        {
            // Convert to the destination color space.
            ImGearRasterProcessing.ConvertColorSpace(page, currentPage.DIB.ColorSpace);
        }
        bool changeDepth = false;
        if (currentPage.DIB.ChannelDepths.Length != page.DIB.ChannelDepths.Length)
        {
            changeDepth = true;
        }
        else
        {
            for (int i = 0; i < currentPage.DIB.ChannelDepths.Length; ++i)
            {
                if (currentPage.DIB.ChannelDepths[i] != page.DIB.ChannelDepths[i])
                {
                    changeDepth = true;
                    break;
                }
            }
        }
        if (changeDepth)
        {
            // Convert to the destination bit depth.
            ImGearRasterProcessing.ChangeChannelDepths(page, currentPage.DIB.ChannelDepths);
        }
        if (ImGearRasterProcessing.Verifier.CanApplyMerge(currentPage, page))
        {
            ImGearRasterProcessing.Merge(currentPage, page, 0, 0, ImGearMergeModes.OVER);
        }
        else
        {
            // Incompatible images. Just replace the current page by page from clipboard.
            this.imGearPage = page;
        }
    }
    else
    {
        this.imGearPage = page;
    }
}

Dim page As ImGearRasterPage = ImGearRasterPage.GetFromClipboard()
If page IsNot Nothing Then
Dim currentPage As ImGearRasterPage = TryCast(Me.imGearPage, ImGearRasterPage)
    If currentPage IsNot Nothing Then
        If Not currentPage.DIB.ColorSpace.Equals(page.DIB.ColorSpace) Then
' Convert to the destination color space.
            ImGearRasterProcessing.ConvertColorSpace(page, currentPage.DIB.ColorSpace)
        End If
Dim changeDepth As Boolean = False
        If currentPage.DIB.ChannelDepths.Length <> page.DIB.ChannelDepths.Length Then
            changeDepth = True
        Else
            For i As Integer = 0 To currentPage.DIB.ChannelDepths.Length - 1
                If currentPage.DIB.ChannelDepths(i) <> page.DIB.ChannelDepths(i) Then
                    changeDepth = True
                    Exit For
                End If
            Next
        End If
        If changeDepth Then
' Convert to the destination bit depth.
            ImGearRasterProcessing.ChangeChannelDepths(page, currentPage.DIB.ChannelDepths)
        End If
        If ImGearRasterProcessing.Verifier.CanApplyMerge(currentPage, page) Then
            ImGearRasterProcessing.Merge(currentPage, page, 0, 0, ImGearMergeModes.OVER)
        Else
' Incompatible images. Just replace the current page by page from clipboard.
            Me.imGearPage = page
        End If
    Else
        Me.imGearPage = page
    End If
End If