DTwainSource::SetCapValues

Top  Previous  Next

Syntax

 

bool DTwainSource::SetCapValues( LONG Cap, const DTwainLongArray& Values, LONG SetType=DTWAIN_CAPSET );

 

bool DTwainSource::SetCapValues( LONG Cap, const DTwainStringArray& Values, LONG SetType=DTWAIN_CAPSET );

 

bool DTwainSource::SetCapValues( LONG Cap, const DTwainDoubleArray& Values, LONG SetType=DTWAIN_CAPSET );

 

bool DTwainSource::SetCapValues( LONG Cap, const DTwainFrameArray& Values, LONG SetType=DTWAIN_CAPSET );

 

Parameters

Cap

Capability value to set.

 

Values

The values used to set the capability.  This argument is ignored if SetType is DTWAIN_CAPRESET.

 

SetType

Capability setting mode.  Either DTWAIN_CAPSET, DTWAIN_CAPSETCURRENT, or DTWAIN_CAPSETAVAILABLE

 

Return Value

true if successful, false if unsuccessful.

 

Comments

The DTwainSource::SetCapValues function sets the Source's capability values.

 

There are four forms of CDTwainSource::SetCapValues.  All the forms are both equivalent in terms of every parameter except the Values parameter.  The lCap parameter is one of the capability constants (for example, DTWAIN_CV_ICAPBITDEPTH or DTWAIN_CV_CAPAUTHOR.  See the main help manual for a complete list of these constants).

 

The SetType determines whether the capability value that will be retrieved is the current value, default value, or all the values supported by the capability. The values of SetType can be one of the following:

 

SetType

Definition

DTWAIN_CAPSET        

Sets the value(s) of the capability.

DTWAIN_CAPRESET

Resets the capability to the default value.

 

If the SetType parameter is omitted, then DTWAIN_CAPSET is assumed and the second argument Values is ignored.  To call SetCapValues easily using DTWAIN_CAPRESET, the following example code can be utilized:

 

DTwainSource Source;

//...

Source.SetCapValues(DTWAIN_CV_ICAPGAMMA, DTwainDoubleArray( ), DTWAIN_CAPRESET );

//...

 

This creates a temporary DTwainDoubleArray, which will be ignored by the SetCapValues function and resets the gamma setting of the device to the default value.

 

The Values parameter will be either an STL vector of long values, string values, double (real) values, or DTwainFrame values.  The type of vector to use depends on the lCap parameter.  If the wrong vector type is used for the lCap value type, DTwainSource::GetCapValues returns false.  The DTWAIN C++ library uses typedef's for the various vector types.  These typedef's that are used for capability setting and retrieval are DTwainLongArray, DTwainStringArray, DTwainDoubleArray, and DTwainFrameArray.  In general, the vector types are determined by the following:

 

If the capability supports an integer type (long, int, boolean, etc.), the vector to use is DTwainLongArray.

If the capability supports a floating point type, the vector to use is DTwainDoubleArray

If the capability supports a string type, the vector to use is DTwainStringArray.

If the capability supports a TW_FRAME type, the vector to use is DTwainFrameArray.

 

To get the data type for a specific capability, you can get the data type defined in the DTWAIN Capability constants in the main help manual, or call DTwainSource::GetCapDataType( ) to determine the type.  Here is a table of the return value from DTwainSource::GetCapDataType, and the correspoding vector type to use:

 

Return from GetCapDataType( )

vector to use

TWTY_INT8      

DTwainLongArray

TWTY_INT16    

DTwainLongArray

TWTY_INT32    

DTwainLongArray

TWTY_UINT8  

DTwainLongArray

TWTY_UINT16

DTwainLongArray

TWTY_UINT32

DTwainLongArray

TWTY_BOOL    

DTwainLongArray

TWTY_FIX32    

DTwainDoubleArray

TWTY_FRAME  

DTwainFrameArray

TWTY_STR32    

DTwainStringArray

TWTY_STR64    

DTwainStringArray

TWTY_STR128  

DTwainStringArray

TWTY_STR255  

DTwainStringArray

 

A return value of false from DTwainSource::SetCapValues could mean one of the following:

 

The source does not support the capability.
The Values parameter specifies the wrong vector type.
DTWAIN was not initialized
The Source is not valid (i.e. was not selected and/or did not open successfully).
The values for the capability to be set for are incorrect.
Bug in the device's Twain driver (i.e. does not allow setting of the value when it should allow it).

 

Since the Values parameter is actually an STL vector, there are a few ways to initialize the vector with the capability values to set.  As an example, to set the capability values for DTWAIN_CV_ICAPXRESOLUTION, the data types that will be stored are DTWAIN_FLOATs.  In this case, the call to DTwainSource::SetCapValues must use a reference to a DTwainDoubleArray as the Values parameter.  

 

To set the available resolutions, the following code snippet shows how this is done:

 

#include <cdtwain.h>

 

using namespace DTWAIN;

 

int main( )

{

   DTwainInterface TI( NULL, NULL ); // start DTWAIN and a Twain session

   DTwainSource Source = DTwainSource::Select( );

 

   // set the available resolution values

   DTwainDoubleArray Resolutions( 2 );

   Resolutions[0] = 200.0;

   Resolutions[1] = 300.0;

 

   // alternately, push_back( ) could have been used

   // DTwainDoubleArray Resolutions;

   // Resolutions.push_back( 200.0 );

   // Resolutions.push_back( 300.0 );

 

   // now set the values

   Source.SetCapValues( DTWAIN_CV_ICAPXRESOLUTION, Resolutions );

}