ExecVariant (ImageKit Control/ Scan Method)

This method retrieves an image from a TWAIN datasource (scan device). This method is recommended when using scripting or other languages that require variant types.

Parameters

Return Value

Returns True (nonzero) when successful, returns False (0) when not successful.

Explanation

The ExecVariant method retrieves an image from a TWAIN datasource (scan device). This method is recommended when using scripting or other languages that require variant types.

Events are generated before, during, and after the scan (BeforeScan, AfterScan, and Scanning events) so it is possible to write processing code in each of these stages of the scan process.

The Index parameter is enabled only when the UiMode property is 2 (ikScanNONUI) and the ScanMode property is 4 or 6 (set for a digital camera). However, in other situations where this array of index values is not needed, please set the Index parameter to NULL or to a dummy array. The Index parameter is used to specify which image is retrieved from the digital camera.

For example, to retrieve the 5th and 8th image from a digital camera, set the Index array parameter to

   Index(0) = 5

   Index(1) = 8

Then set the number of elements in the Index array (2) into the PageCount property. Some scan devices do not support these functions. In such cases, only the supported functions are used to scan the image.

Prior to executing the ExecVariant method, you must execute the Initialize method.

If the OpenDS method is executed prior to the ExecVariant method, then while the scan device is open, other applications can not use that scan device and it becomes the exclusive datasource for this execution.

Also see the Exec method.

The ExecVariant method corresponds to the Scan Control's ScanExec method in earlier versions of the ImageKit.

<The following properties should be set prior to executing the ExecVariant method>

[Required properties]

• DsName - if this is blank, then select the scan device by executing the Select method. Note: If the OpenDS method is executed prior to executing the DsName method then the DsName is disabled and the open scan device is used.
• TransferMode
• Compression
• UiMode
• ExtUiMode  - This property is required only when using Epson scanner drivers.

[These properties may be required depending on the settings]

• FileFormat
• FileName
• InformationFileName
• JpegQuality

[If the UiMode property is 2]

1. When using a scanner it is recommended that these properties be set when the UiMode property is 2:
   AdjustGamma, BitDepth, BitDepthReduction, BorderDetection, Brightness, ColorBWRatio, Contrast, Deskew , DropoutColor, DynamicThreshold, FocusPosition, Gamma, HalfTone, Highlight, IgnoreBackColor, ImageFilter, Indicator, MoireFilter, NoiseFilter, Orientation, OverScan, PageCount, PaperSize, PixelType, RemoveHole, Rotation, ScanMode, ScanningSpeed, Shadow, Sharpness, SkipBlankPage, SkipBlankThreshold, TextEnhancement, Threshold, UnitFlag, UnitMode, XResolution, XScaling, YResolution, YScaling, PaperSize<=0: RectBottom , RectLeft, RectRight, RectTop
   
   Note: The AdjustGamma, ColorBWRatio, DynamicThreshold, FocusPosition, IgnoreBackColor, MoireFilter, RemoveHole, RotateBack, ScanningSpeed, Sharpness, SkipBlankThreshold, TextEnhancement properties are sometimes disabled depending on the scan driver.
   
   
2. When using a digital camera, it is recommended that these properties be set when the UiMode property is 2:
   PageCount, ScanMode , UnitMode
   
        Note: If the ScanMode property is 1, then the XResolution should be set to 0.

<The following properties are set after the scan has executed>

BitDepth, Compression, ErrorStatus, FileFormat (when using file transfer method), PixelType , RectBottom, RectLeft, RectRight, RectTop, ScanCount, UnitMode, XResolution, YResolution

For details, please refer to the respective properties' explanations.

Important points when using a custom built user interface (UiMode = 2)

When UiMode is 2, depending on the scan device and the property values set, the scan can fail. For the most part the causes for scan failure when the UiMode is 2 can be traced to the following:

1. The scan units set are not supported by the scan device. The supported scan unit values can be retrieved using the GetCapEnum or the GetCapEnumVariant method.
2. The pixel type set is not supported by the scan device. The supported pixel type values can be retrieved using the GetCapEnum or the GetCapEnumVariant method.
3. The bit count set is not supported by the scan device. The supported bit count values can be retrieved using the GetBitDepth or the GetBitDepthVariant method.
4. The resolution set is not supported by the scan device. The supported resolution values can be retrieved using the GetCapEnum, the GetCapEnumVariant, the GetCapRange, or the GetCapRangeVariant methods.
5. The paper size set is not supported by the scan device. The supported values can be retrieved using the GetCapEnum or the GetCapEnumVariant method.
   1. If settings for paper size are not supported at all, then set the PaperSize property to 0 and set the appropriate scan area in the RectLeft, RectTop, RectRight, and RectBottom properties. If the scan area is not correctly set (i.e. it is smaller than the minimum or larger than the maximum), the scan can fail. The proper scan area values can be retrieved using the GetMinimumSize(GetMinimumSizeVariant) and GetPhysicalSize(GetPhysicalSizeVariant) methods.
   2. If paper size settings are supported and the scan still fails, check to make sure the PaperSize property is set to a value other than 0.