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:
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:
A return value of false from DTwainSource::SetCapValues could mean one of the following:
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 ); }
|