Communicating with the Clipboard

Fastgraph includes two functions for copying data between the active virtual buffer and the Windows clipboard. The fg_vb2clip() function copies the specified rectangular region from the active virtual buffer to the clipboard, while fg_clip2vb() copies the clipboard contents to the specified position in the active virtual buffer.

The fg_vb2clip() function has four parameters that specify the screen space minimum x, maximum x, minimum y, and maximum y coordinates of the region to copy from the active virtual buffer. It constructs a Windows device-independent bitmap (DIB) from this region and writes the DIB to the clipboard, along with palette data for the active logical palette. The fg_vb2clip() return value will be 0 if successful, -1 if another application has control of the clipboard, or -2 if there is insufficient free global memory to create the DIB.

The fg_clip2vb() function's first four parameters specify the region in the active virtual buffer that will receive the clipboard data, in the same order as fg_vb2clip(). If the width of the clipboard image is less than the width of this region, the remaining pixels in each row of the transfer region will be left unchanged. Similarly, if the height of the clipboard image is less than the height of the transfer region, pixels above the image height will be unaffected. In other words, fg_clip2vb() will copy the image to the lower left corner of the truncated transfer region. If the width or height of the clipboard image exceeds the limits of the transfer region, fg_clip2vb() will truncate the clipboard image at the boundaries of the transfer region. The fifth fg_clip2vb() parameter is a bit mask that controls how the image is displayed and whether we cut or copy the clipboard contents, as shown here:

All other flag bits are reserved and should be zero to guarantee compatibility with future releases. The fg_clip2vb() return value will be 0 if successful, -1 if another application has control of the clipboard, -2 if the clipboard does not contain a DIB image, or -3 if the clipboard image does not have the same color depth as the active virtual buffer.