Getting and Setting Capabilities

Each TWAIN source may support a number of capabilities. These capabilities dictate the behavior of the TWAIN source. Before acquiring images from the selected TWAIN source, the user may wish to examine and change the capability settings for that source.

It is possible to check whether the scanner installed on the system supports certain capabilities. For more information, refer to How to Find Out Whether Your Scanner Supports Certain Capabilities Using Twacker, found on http://support.leadtools.com/SupportPortal/cs/forums/3781/ShowPost.aspx.

LEADTOOLS provides both low-level and high-level options for getting and setting capabilities. The low-level options get and set capabilities individually. The high-level options perform much of the low-level work automatically by interacting with the TWAIN driver directly, allowing the programmer to get and set a series of universal settings common to all TWAIN compliant scanner hardware without having to handle individual capabilities directly. Note that these universal settings do not cover all of the available TWAIN capabilities. Some capabilities can only be retrieved and set using the low-level methods.

Low-Level:

$image\sqrblit.gif$ To get information on a specific capability (current, default, or all possible values) call the GetCapability method if you are working in MFC. The capability will be retrieved via a pointer to a created ICapability interface. If you are working in VB, call the GetCapability2 method. The capability will be retrieved via a pointer to a created ILEADTwainCapability interface.

$image\sqrblit.gif$ To set a specific capability to a new value or to reset the value of a capability to the default value, call the SetCapability method if you are working in MFC. If you are working in VB, call the SetCapability2 method.

$image\sqrblit.gif$ To get all available values for a specific capability supported by the selected TWAIN source, call the QueryCapability method.

$image\sqrblit.gif$ To get the number of capabilities supported by the selected TWAIN source, look at the CapsCount property.

$image\sqrblit.gif$ To get an array of capabilities supported by the selected TWAIN source, look at he Capability property

High-Level:

The GetProperties method and the SetProperties method allow the user to get and set a series of universal settings that are common to all TWAIN compliant scanner hardware, reducing the need to handle individual capabilities directly. Note that not all capabilities can be changed using the above properties. Depending on the TWAIN source, some capabilities can only be retrieved and set using the low-level GetCapability and SetCapability methods. These two methods set and retrieve the following properties to and from the TWAIN driver:

$image\sqrblit.gif$ ImageEffects property: a read-only ILTImageEffects object containing the PixelFlavor, ColorScheme, HighLight, Shadow, Brightness, Contrast, and HalfTone properties. These properties are set to the TWAIN driver through the ImageEffects property when the SetProperties method is called.

$image\sqrblit.gif$ DataTransfer property: a read only ILTDataTransfer object containing the FillOrder, BufferMemoryCompression, TransferMode, ScanFileFormat, MemoryBufferSize, EnableSaveMultipageFile, EnableAppendToFile, and EnableDumpMemoryBuffersToFile properties. These properties are set to the TWAIN driver through the DataTransfer property when the SetProperties method is called.

$image\sqrblit.gif$ ImageResolution property: a read-only ILTImageResolution object containing the Unit, BitsPerPixel, HorizontalResolution, VerticalResolution, XScaling, YScaling, and RotationAngle properties. These properties are set to the TWAIN driver through the ImageResolution property when the SetProperties method is called.

$image\sqrblit.gif$ EnableAutoFeed property: flag indicating whether or not to use the Auto-Feed capability of a selected TWAIN source.

$image\sqrblit.gif$ MaxPagesNumber property: determines the maximum number of pages to retrieve from a TWAIN source.

$image\sqrblit.gif$ DuplexScanning property: a read-only value that specifies the type of duplex scanning used by a TWAIN source. This value is set by the hardware and cannot be altered by the programmer.

$image\sqrblit.gif$ The LeftMargin, RightMargin, TopMargin, and BottomMargin properties: values that determine the left margin, right margin, top margin, and bottom margin, respectively, of the scanning area.

There are several transfer option capabilities that control the transfer mode, file name, file format, and compression. The values for these options are contained in the TransferMode Property, TransferFileName Property, TransferFileFormat Property and TransferCompressionType Property. The current values can be obtained or modified collectively using the SetTransferOptions and the GetTransferOptions methods.

In addition to the transfer options mentioned above, the transfer modes supported by the TWAIN source can be obtained by using IsFileTransferAvailable, IsMemoryTransferAvailable and IsNativeTransferAvailable properties.

When transferring files from the TWAIN source there is a maximum number of files that can be transferred. To get or set the current value, use the MaxXferCount property.

There are many capabilities associated with various image characteristics, such as image resolution, image frame, image unit, and bits per pixel. The current values for these can be obtained or changed using the following properties:

ImageBitsPerPixel property

Image contrast, highlight and brightness capabilities can be obtained or changed using the following properties:

ImageBrightness property

ImageContrast property

ImageHighlight property

The RGB elements used by the TWAIN source are set by calling the SetRGBResponse method. This method uses the values in the following properties to set the current TWAIN source:

RGBElements property

RGBElementsCount property

The RGBElements property contains a pointer to an ITwainRGBElements object that references the following properties:

These properties must be set before calling the SetRGBResponse method in order to set the RGB elements for the TWAIN source.

If the TWAIN source supports duplex scanning, the duplex mode can be enabled or disabled by setting the EnableDuplex property. To get the current duplex mode, read the DuplexMode property.

The page size and orientation used during image acquisition can be obtained or set by using the following properties:

PaperSize property

PaperDirection property

During the actual acquisition process, you can elect to have a progress indicator displayed. The ShowProgress method lets you hide or display the progress indicator.

After setting the desired capabilities call the Acquire method to scan the pages.

When setting and getting the capabilities, it may be necessary to create a container associated with that capability. For more information on containers, refer to How to Work with the Containers if you are working in MFC. If you are working in VB, refer to How to Work with Containers – Visual Basic.