The "clipboard" functions provide the ability to cut, copy, and paste to and from the clipboard. With this function group, you can cut or copy all or a portion of an image to the system clipboard, paste the contents of the clipboard into a new HIGEAR image, or even "paste-merge" the contents of the system clipboard into a pre-existing image. You can also check for the existence of data in the clipboard, and check the size of an image in the clipboard. For separate descriptions of each clipboard function and additional sample code, please refer to the Clipboard Functions section in the Core Component API Function Reference.

This section provides information about the following:

Copying/Cutting to the Clipboard

You may cut or copy the entire HIGEAR image, or just a specified rectangular portion of the image, to the clipboard. To copy to the clipboard, call the function IG_clipboard_copy() with the image's HIGEAR handle, and the coordinates of the AT_RECT rectangle that you would like to save to the clipboard. Pass NULL as the rectangle's value to if you want to copy the entire image to the clipboard.

To cut to the clipboard, call IG_clipboard_cut(). The only difference in the prototype of these functions is that IG_clipboard_cut() contains an extra argument for specifying what color pixel to use to replace the pixels that are "cut away". This pixel color argument is usually set to black or white.

Checking the Contents of the Clipboard

ImageGear provides two functions for examining the contents of the clipboard:

• IG_clipboard_paste_available_ex() lets you know whether there is an image in the system clipboard. It is recommended that you always call this function before pasting from the clipboard, and also before calling IG_clipboard_dimensions(). This function returns an AT_BOOL value, where TRUE means that there is a paste-able image in the clipboard.
• IG_clipboard_dimensions() returns three values to you: the width of the image (in pixels), the height of the image (in pixels), and the number of bits per pixel of the image on the clipboard. Using these values, you can determine whether or not the image dimensions are appropriate for your purposes.

Pasting an Image from the Clipboard

There are two ImageGear functions for pasting the image from the clipboard:

• IG_clipboard_paste() creates a new HIGEAR image into which it pastes the contents of the clipboard. 
• IG_clipboard_paste_merge_ex() pastes the clipboard image into an existing HIGEAR image at the specified position. If the clipboard image's width is greater than the image into which it is being pasted, it will automatically be cropped to fit; the size of the original HIGEAR image will not change.

Before you call IG_clipboard_paste_merge_ex(), you can call the function IG_clipboard_paste_op_set() to specify the kind of arithmetic operation you want to apply to the pixels of the two bitmaps that intersect during the paste-merge. IG_clipboard_paste_op_set() takes an AT_MODE constant (defined in accucnst.h) that has a prefix of IG_ARITH_. The full group of arithmetic constants is listed under the function description for IG_clipboard_paste_op_set(). ImageGear also supplies a companion reading function IG_clipboard_paste_op_get() to read the current setting for the paste-merge arithmetic operation. See Example code below:

AT_DIMENSION nWi, nHi;
UINT nBpp;
BOOL bPasteAvail;
AT_ERRCOUNT nErrcount;
HIGEAR hIGear, hIGear2;
AT_RECT rcClipRect;
nErrcount = IG_load_file("picture.bmp", &hIGear);
if (nErrcount == 0)
{
        nErrcount = IG_image_dimensions_get ( hIGear, &nWid, &nHi, &nBpp );*/
        if ( nErrcount == 0 ) /* If valid image dimensions */
        {/* send the bottom half of the image*/
                rcClipRect.top = nHi/2; /* to the clipboard */
                rcClipRect.left = 0; 
                rcClipRect.right = nWi - 1;
                rcClipRect.bottom = nHi - 1;
                nErrcount = IG_clipboard_copy (hIGear, &rcClipRect);
        }
if (nErrcount == 0)
{
/*load a second image into which to merge the clipboard contents*/
                nErrcount = IG_load_file("picture2.bmp", &hIGear2);
}
if (nErrcount == 0)
{
        nErrcount = IG_clipboard_paste_available_ex(&bPasteAvail);
        if (bPasteAvail == TRUE)
        {
        /* set the paste-merge arithmetic operation to Img1^Img2 */
        nErrcount = IG_clipboard_paste_op_set(hIGear, 
                                IG_ARITH_XOR);
        /* merge clipboard's rectangular contents with upper left
         corner at position 0,0                 */
                nErrcount = IG_clipboard_paste_merge_ex(hIGear2, 0 , 0);
                }
}