DTWAIN_AcquireToClipboard
|
The DTWAIN_AcquireToClipboard starts the image acquisition from a Source and transfers the image to the Windows Clipboard.
DTWAIN_ARRAY DTWAIN_AcquireToClipboard (
Parameters Source Specifies a selected TWAIN Source.
PixelType Specifies the pixel type of the image
NumPages Specifies the number of pages to acquire.
TransferMode
Specifies which transfer mode to use.
bDiscardImages Specifies whether images are destroyed instead of saved in returned DTWAIN_ARRAY.
bShowUI Specifies whether the Source displays the default User Interface.
bCloseSource Specifies whether the Source should be closed after the User Interface is shut down.
pStatus Points to a variable that will be filled in with an error status value or NULL if no error status is desired.
Return Values: If the function succeeds, a DTWAIN_ARRAY describing the attempted acquisitions is returned. If the function fails, NULL is returned.
Comments: Starts the image acquisition from a TWAIN device and saves the acquired image(s) to the Windows Clipboard. This allows an application to simply use the "Paste" function to retrieve the image data (if the image is a Device Independent Bitmap). Most applications implement "Paste" as retrieving data from the Clipboard.
The bDiscardImages flag determines whether the images that are acquired, except for the last image acquired are to be discarded. If the value of bDiscardImages is TRUE, no images are saved within the returned DTWAIN_ARRAY, and the returned DTWAIN_ARRAY is equal to 1 on success. If bDiscardImages is FALSE, the returned DTWAIN_ARRAY is an array of acquisitions attempted, along with the array of images (see the return value to DTWAIN_AcquireNative).
Note that this behavior of the bDiscardImages flag is only valid if the TWAIN mode is DTWAIN_MODAL (see DTWAIN_SetTwainMode). If the TWAIN mode is DTWAIN_MODELESS, all of the images are saved, and it is the responsibility of the application to discard the image memory.
Regardless of the state of the bDiscardImages parameter, only the last page of the acquisition is saved to the clipboard if multiple pages are acquired, or if the program allows more than one acquisition to be attempted per open Source session.
The arguments PixelType, Source, MaxPage, bShowUI and pStatus all have the same definitions as DTWAIN_AcquireNative.
The TransferMode determines whether the native or buffered mode will be used to acquire the image(s). To control which image transfer mode the Source will use, the TransferMode must be one of the following values
It is advised that you should be familiar with the Window's API Clipboard functions. You will need to use them if you want to retrieve the DIBs from the clipboard successfully. The data that is stored in the clipboard is of type CF_DIB.
This function is suitable for Visual Basic programmers who are familiar with handling the Clipboard object. A call to Clipboard.GetData using the vbCFDIB data format is all that is required for a VB program to copy and display the data in an image or picture control.
Note: If multiple pages are desired using the clipboard, the application must be set up to capture DTWAIN notifications that indicate when a page has been transferred successfully, since each new page saved to the clipboard will overwrite any previous page. If this is not done, only the last page from a multi-page acquire will be saved to the clipboard when the Source UI is closed.
TWAIN State Transitions State 4(if Source is not opened)
Prerequisite Function Call(s) DTWAIN Source Selection Function
See Also DTWAIN_AcquireBuffered, DTWAIN_AcquireNative, DTWAIN_AcquireFile |