ImageGear for C and C++ on Windows v19.1 - Updated
IG_ISIS_choice_get_rational
API Reference Guide > ISIS Component API Reference > ISIS Component Functions Reference > Choice Functions > IG_ISIS_choice_get_rational

Get a valid rational choice value from a driver.

Declaration:

 
Copy Code
AT_ERRCOUNT ACCUAPI IG_ISIS_choice_get_rational(
        HISISDRV hDriver,
        AT_MODE nTag,
        WORD wIndex,
        LPAT_ISIS_RAT lpValue
);

Arguments:

Name Type Description
hDriver HISISDRV The handle to the driver.
nTag AT_MODE The tag for which a valid rational value is being requested.
wIndex WORD An index to a particular element of the array of valid tag values.
lpValue LPAT_ISIS_RAT A pointer to a RAT buffer that will contain the result of IG_ISIS_choice_get_rational.

Return Value:

Error count.

Supported Raster Image Formats:

This function does not process image pixels.

Example:

The following example first determines whether the choices of a rational value, IG_ISIS_TAG_XRESOLUTION, are implemented as a range or a list, then gets each value and prints it to the standard output:

 
Copy Code
nErrCount = IG_ISIS_choice_get_flags(hDriver, IG_ISIS_TAG_XRESOLUTION, &lValue);
        if (nErrCount != IGE_SUCCESS)        return nErrCount;
/* If choices are stored as a range, get the low, high, and step:                                                                                                        */
        if (lValue & IG_ISIS_CONT_RANGE) {
                nErrCount = IG_ISIS_choice_get_rational(hDriver, IG_ISIS_TAG_XRESOLUTION,
                                                 IG_ISIS_CHOICE_LOW, &ratResLo);
                if (nErrCount != IGE_SUCCESS)        return nErrCount;
                nErrCount = IG_ISIS_choice_get_rational(hDriver, IG_ISIS_TAG_XRESOLUTION,
                                                 IG_ISIS_CHOICE_HIGH, &ratResHi);
                if (nErrCount != IGE_SUCCESS)        return nErrCount;
                nErrCount = IG_ISIS_choice_get_rational(hDriver, IG_ISIS_TAG_XRESOLUTION,
                                                 IG_ISIS_CHOICE_STEP, &ratResStep);
                if (nErrCount != IGE_SUCCESS)        return nErrCount;
                printf("  Range:\n   %ld%ld - %ld%ld by %ld%ld\n",
                                ratResLo.Num, ratResLo.Denom,
                                ratResHi.Num, ratResHi.Denom,
                                ratResStep.Num, ratResStep.Denom);
        }
/* If choices are stored as a list, get and print the entire list:                                                                                                               */
        if (lValue & IG_ISIS_CONT_LIST) {
                nErrCount = IG_ISIS_choice_get_count(hDriver, IG_ISIS_TAG_XRESOLUTION, &wCount);
                if (nErrCount != IGE_SUCCESS)        return nErrCount;
                printf("  Values:\n");
                for (w=0; w < wCount; w++) {
                        nErrCount = IG_ISIS_choice_get_rational(hDriver, IG_ISIS_TAG_XRESOLUTION, w,
&ratRes);
                        if (nErrCount != IGE_SUCCESS)        return nErrCount;
                        printf("   %3ld%ld" , ratRes.Num, ratRes.Denom);
                        if ((w%7) == 6 || (w == wCount-1))
                                printf("\n"); // seven per line
                }

Remarks:

The IG_ISIS_choice_get_rational function fills in lpValue with the value referenced by wIndex from tag nTag.

This function must be used only for tags which have a type of IG_ISIS_TAG_TYPE_RATIONAL. Use the IG_ISIS_tag_get_type function to determine the type of a tag.

The IG_ISIS_choice_get_count function can be used to determine the total number of legal values for a tag. wIndex must be at least 0 and at most the value returned by IG_ISIS_choice_get_count - 1. The constants IG_ISIS_CHOICE_LOW and IG_ISIS_CHOICE_HIGH can be used to retrieve the 0th and nth values of a list or range; however, keep in mind that a list must be sorted from low to high values for these constants to return the actual low and high values of the list. Also, IG_ISIS_CHOICE_STEP can be used if the flag IG_ISIS_CONT_RANGE is set. The value returned by IG_ISIS_choice_get_rational using a wIndex value of IG_ISIS_CHOICE_STEP is the difference between any two consecutive values.

The toolkit's RAT value consists of a signed 32-bit numerator (Num) and a signed 32-bit denominator (Denom), comprising a fractional value: The individual values of a AT_ISIS_RAT type can be accessed as conventional elements:

 
Copy Code
     ratValue.Num
        ratValue.Denom

See Also:

IG_ISIS_choice_get_count

IG_ISIS_tag_get_type