DTwainRange::GetNearestValue

Syntax

DTwainDoubleArray:

double GetNearestValue( double Value, int RoundType=DTWAIN_ROUNDNEAREST ) const;

DTwainLongRange:

long GetNearestValue( LONG Value, int RoundType=DTWAIN_ROUNDNEAREST ) const;

Parameters

Value

Value to search for.

RoundType

Determines whether to round to the nearest range value, round up to the next range value, or round down to the previous range value.

Return Value

If successful, returns a value defined by the range that is closest to Value.

Comments

DTwainRange::GetNearestValue gets the range value that is closest to the given value Value.  The RoundType argument determines whether to round up, down, or to the nearest range value. RoundType can be one of the following:

If Value is less than the DTwainRange::GetMin, then the minimum value of the range is returned.  If Value is greater than DTwainRange::GetMax, the maximum value of the range is returned.

An example is as follows:

If the DTwainRange has the following characteristics:

minimum = -10

Maximum Value = 30

Step size = 5

The expanded range will consist of the following values

-10, -5, 0, 5, 10, 15, 20, 25, 30

A call to DTwainRange::GetNearestValue( 12 ) will return 10, since 12 is closest to the range value 10, and the RoundType is by default DTWAIN_ROUNDNEAREST.

This function is very useful for device capability value setting.  If a capability returns a range of values, and your application must choose a value within the range, DTwainRange::GetNearestValue will return a valid number in the range.  This allows your application to set a capability with a valid value.  For example, many Sources use a range to define the valid settings for the DTWAIN_CV_ICAPCONTRAST capability (the contrast setting).  If your application needs to set the contrast, you must provide a valid number defined by the range.  DTwainRange::GetNearestValue will always return a valid number that is closest to the given number.