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

Save current tag value(s) in memory.

Declaration:

 
Copy Code
AT_ERRCOUNT ACCUAPI IG_ISIS_tag_save_value(
        HISISDRV hDriver,
        AT_MODE  nTag
);

Arguments:

Name Type Description
hDriver HISISDRV The handle to the driver.
nTag AT_MODE Specifies that tag whose value is to be saved. Specify a value of zero to save all tags.

Return Value:

Error count.

Supported Raster Image Formats:

This function does not process image pixels.

Remarks:

The IG_ISIS_tag_save_value function saves the value of a specified tag, or the values of all tags, in a last-in/first-out stack in memory, allowing an application to implement cancel or undo functions in settings dialogs so that previous values can be restored.

Use IG_ISIS_tag_save_value to save the values of the specified nTag or of all tags (by setting nTag to zero). It is strongly recommended that all calls to IG_ISIS_tag_save_value use a tag value of zero for consistency. Each IG_ISIS_tag_save_value call must have a corresponding call to either IG_ISIS_tag_flush_value or IG_ISIS_tag_restore_value.

Generally, call IG_ISIS_tag_save_value before offering the user the opportunity to change the values of tags (for example, when displaying a Scanner Settings dialog box). The user can either confirm the settings (click OK) or revert to the previous settings (click Cancel). If the user confirms the settings, call IG_ISIS_tag_flush_value to discard the saved settings and free the memory they occupied. If the user wants to revert to the previous settings, call IG_ISIS_tag_restore_value to restore the saved settings to their previous values and free the memory they occupied.

Multiple saves are possible, to support the implementation of multi-level undo or nested settings dialogs. Call IG_ISIS_tag_save_value before presenting each new dialog. In the example illustrated below, IG_ISIS_tag_save_value is called a second time when the user clicks the Next button, storing a second set of saved values on the stack. If the user clicks OK in the Next Settings dialog, the settings values saved when the Next Settings dialog was spawned are restored and the corresponding saved values flushed (but the first set of values saved are still on the stack). If the user clicks Cancel, the settings that were in effect when the Next Settings dialog was spawned are restored. Once back at the original Settings dialog, clicking OK saves whatever settings are in effect at that moment, flushing the first values that were saved on the stack. Clicking Cancel restores all previous settings that were in effect before the user took any action (because the settings that are restored at this point are the ones that were saved before any action was taken in the Next Settings dialog).

This function is included to allow application developers to implement their own multi-level settings dialogs. The Scanner Settings and More Settings dialogs that are built-into the toolkit and many ISIS drivers implement this functionality automatically and do not require the use of this function.

Example:

 
Copy Code
IG_ISIS_tag_save_value(hDriver, 0);      /*One group of settings on stack        */IG_ISIS_tag_restore_value(hDriver, 0);        /* No settings saved                     */IG_ISIS_tag_save_value(hDriver, 0);  /* One group of settings on stack       */IG_ISIS_tag_save_value(hDriver, 0);   /* Two groups of settings on stack      */IG_ISIS_tag_save_value(hDriver, 0);   /* Three group of settings on stack      */IG_ISIS_tag_restore_value(hDriver, 0);       /* Two groups of settings on stack      */IG_ISIS_tag_flush_value(hDriver, 0);  /* One group of settings on stack                                */IG_ISIS_tag_restore_value(hDriver, 0);       /* No settings saved                     */

See Also

IG_ISIS_tag_flush_value

IG_ISIS_tag_restore_value