Callback Functions

ImageGear provides callback function support for load, save, print, and other operations to enable your application to control these processes. Callback functions are functions for which you write the code, and whose names you provide to ImageGear. ImageGear will call them at appropriate breakpoints in an operation (such as after each raster line has been processed), at which time your function may modify image data, display status information, or perform other auxiliary operations specified before returning control to ImageGear.

This section discusses how to declare, code, and invoke an ImageGear callback function; how to register an ImageGear callback function; and how to work with the status bar and tag callback functions.

Callbacks are actually function types (or templates) where you can include your own code to carry out extra operations during normal ImageGear file processing. Callbacks can be passed data, return data, or both. All callback type names begin with the prefix "LPFNIG" which stands for "Long Pointer to a FuNction of ImageGear". Due to this unusual prefix, their descriptions can easily be found in the section Core Component Callback Functions Reference in the Core Component API Function Reference.

Some callback functions return a Boolean value to ImageGear, indicating whether you want ImageGear to continue the operation, disregard the instructions in the callback, or abort an operation. Most callbacks are VOID, exchanging their information through their arguments.

How a callback function is coded, declared to ImageGear, and invoked by ImageGear, is illustrated by the simple examples below in which an application calls function IG_load_file_display() to load and then display an image. IG_load_file_display() will automatically call your callback of type LPFNIG_LOAD_DISP.

The following example shows a call to register a display callback and the callback itself:

	Copy Code
VOID ACCUAPI my_set_attributes_func ( LPVOID lpPrivateData, /* Ptr to private data area / HIGEAR hIGear / Handle of loaded image / ) { / This callback function disables centering of the image: */ IG_dspl_layout_set( hIGear, IG_GRP_DEFAULT, IG_DSPL_ALIGN_MODE, NULL, NULL, >NULL, 0, IG_DSPL_ALIGN_X_LEFT\|IG_DSPL_ALIGN_Y_TOP, 0, 0.0 ); return; }

Copy Code

VOID ACCUAPI  my_set_attributes_func
  (
      LPVOID  lpPrivateData, /* Ptr to private data area      */ 
      HIGEAR  hIGear         /* Handle of loaded image         */ 
   )
{
/* This callback function disables centering of the image: */
IG_dspl_layout_set( hIGear, IG_GRP_DEFAULT, IG_DSPL_ALIGN_MODE, NULL, NULL, >NULL,
0, 
IG_DSPL_ALIGN_X_LEFT|IG_DSPL_ALIGN_Y_TOP, 0, 0.0 ); 
return;
}

In response to the above call, ImageGear loads the image, creates a DIB and a HIGEAR data structure, and then calls your callback function. When your callback function returns, ImageGear will display the image, and then return to the statement following IG_load_file_display().

Note that your module containing the IG_load_file_display() should contain in its initial definitions a function prototype or declaration for the callback function. There are two ways that the callback can be declared:

By prototype:

	Copy Code
VOID ACCUAPI my_set_attributes_func ( LPVOID lpPrivate, HIGEAR hIGear );

By declaration:

	Copy Code
LPFNIG_LOAD_DISP my_set_attributes_func;

If you do not write code for a callback function type that is part of a normal API call, such as IG_load_file_display(), you can just pass in a NULL for the callback parameter.

This section also provides information about the following: