DTWAIN_SetAcquireArea

The DTWAIN_SetAcquireArea function sets or resets the current image acquisition area using the Twain device's support for setting the area.

DTWAIN_BOOL DTWAIN_SetAcquireArea (

DTWAIN_SOURCE	Source,
LONG	SetType,
DTWAIN_ARRAY	SetValues,
DTWAIN_ARRAY	ActualValues );

Parameters

Source

An open TWAIN Source.

SetType

Indicates whether to set or reset the area dimensions

SetValues

A DTWAIN_ARRAY containing the values to set the area or NULL.

ActualValues

A DTWAIN_ARRAY containing the values that the Source actually used to set the area or NULL.

Return Values

The return value is TRUE if successful. Otherwise FALSE is returned.

Comments

The DTWAIN_SetAcquireArea function sets or resets the image acquisition area of the Source Source. The DTWAIN_SetAcquireArea uses the TWAIN device's settings for valid acquisition areas.

Note that DTWAIN_SetAcquireArea2 is the more reliable function than DTWAIN_SetAcquireArea in setting the area to acquire, due to the fact that DTWAIN_SetAcquireArea relies solely on the TWAIN Source to set the acquisition area. Many times, the Source will not set the area specified in DTWAIN_SetAcquireArea. Use DTWAIN_SetAcquireArea if you need to set the acquisition area for non-DIB image data (i.e. DTWAIN_AcquireBuffered for compressed streams, or DTWAIN_AcquireFile / DTWAIN_AcquireFileEx with the DTWAIN_USESOURCEMODE flag set).

The SetType can be one of the following:

SetType	Definition
DTWAIN_AREASET	Sets the current values for the image acquisition area.
DTWAIN_AREARESET	Sets the default values for the image acquisition area.

The DTWAIN_ARRAY SetValues is of type DTWAIN_ARRAYFLOAT must be set with the new values to use for the image acquisition area. The values are ordered in the same manner as in DTWAIN_GetAcquireArea.

Position in Array	Definition
0, 1	Upper left (0), top (1) position of rectangle.
2, 3	Lower right (2), bottom (3) position of rectangle.

If SetType is DTWAIN_AREARESET, the SetValues argument is ignored. In this case, SetValues should be NULL.

The DTWAIN_ARRAY ActualValues can be either a DTWAIN_ARRAY of type DTWAIN_ARRAYFLOAT, or NULL. If the value is a valid DTWAIN_ARRAY, ActualValues is filled on return with the actual values that were used to set the acquire area. Sometimes the values requested in SetValues are not used by the Source, so the Source sets the acquire area to the closest values that it will be able to handle. Sometimes this may be the default acquisition area.

If the ActualValues is NULL, DTWAIN will not attempt to determine what the actual values that were used to set the image acquisition area, and the ActualValues parameter is ignored. If SetType is DTWAIN_AREARESET, the ActualValues will be filled with the default acquisition area values.

The following topic discusses getting the current unit of measure for the acquisition area

Getting the current unit of measure.

TWAIN State Transitions

The Source must be in State 4. or higher (depending on the capability).

Prerequisite Function Call(s)

DTWAIN_SysInitialize

DTWAIN Source Selection Function