DTwainAcquirer::SetMultiPageFileMode

Syntax

DTwainAcquirer& SetMultiPageFileMode( bool bMode=true, DTwainMultiPageModeType mType= MULTIPAGEMODE_DEFAULT );

Parameters

bMode

Sets whether a multi-page image file will be created when acquiring multiple pages.

mType

Indicates when the multiple pages will be collated to form a single file.

Return Value

Returns reference to current DTwainAcquirer object (*this).

Comments

DTwainAcquirer::SetMultiPageFileMode is only available when acquiring to a file, and for TIFF, PDF, PostScript, and PCX file formats.  By default, multi-page image file creation is turned off when the DTwainAcquire object is created.  If the multi-page file mode is turned off, individual TIFF, PDF, Postscript or PCX files will be created for each page acquired.

The mType parameter determines when the images that are being acquired will be finally saved to the file, and the image file closed.  If mType is MULTIPAGEMODE_DEFAULT, then the pages are saved whenever the last page is acquired in a single acquisition.  This means that if you have a set of pages in a document feeer, once the last page is acquired, all the pages acquired are automatically saved to a file.  With this option, you cannot acquire a set of pages, acquire another set of pages, and then save these two sets of pages to a file (if the option of saving multiple pages from different acquisitions are desired, use either MULTIPAGEMODE_UICLOSE or MULTIPAGEMODE_SOURCECLOSE defined below).  For most purposes, the MULTIPAGEMODE_DEFAULT processing should be used.

If mType is MULTIPAGEMODE_UICLOSE, then the pages are saved whenever the user closes the TWAIN user interface.  This will allow you to acquire pages from a single sheet device (a flatbed scanner for example), and choose to save all of the acquired pages to an image file when the user closes the user interface.  Also, if you want to acquire multiple pages, acquire another set of pages, etc. and save all these pages to a single file, the MULTIPAGEMODE_UICLOSE option can be used to facilitate this.  Once the user interface is closed, the entire set of pages that are pending to be saved are saved to the file, and then released from memory.

If mType is MULTIPAGEMODE_SOURCECLOSE, then the pages are saved whenever the application closes the TWAIN Source.  This is accompished either when the TwainInterface object is destroyed, or when the DTwainSoruce::CloseSource function is called.  This mode is useful if you are acquiring with no user-interface, and the device is a flatbed scanner.  Since the application has control of closing the Source, the application can constantly acquire pages from the scanner by calling DTwainAcquirer::Acquire multiple times, and save all of the pages when the Source is closed.   Basically, this option is similar to MULTIPAGEMODE_UICLOSE with the exception that the pages are closed once the Source (not just the user interface) is closed.  Once the Source is closed, the entire set of pages that are pending to be saved are saved to the file, and then released from memory.

Please note that if you wish to control exactly when to save pages, the DTwainAcquirer::FlushPages also gives you the option to save the pages at any time.  This will give you the flexibility of saving the pages that have been acquired whenever your application feels necessary to do so.