Legacy Document

Inside Macintosh: Advanced Color Imaging Reference /

Chapter 3 - ColorSync Manager Reference for Applications and Device Drivers / ColorSync Manager Functions

Application-Defined Functions for the ColorSync Manager /

MyCMBitmapCallBackProc

Application-defined function that reports on the progress of a color-matching or color-checking session being performed for a bitmap or a pixel map.

This application-supplied function must conform to the following declaration, although the function name is arbitrary:

pascal Boolean MyCMBitmapCallBackProc (
long progress, 
void *refCon);

progress

A byte count that begins at an arbitrary value and counts down to 1 when the matching is complete.

refCon

The reference constant passed to your MyCMBitmapCallBackProc function each time the color management module (CMM) calls your function.

function result

A result code of type Boolean. A return value of false indicates the color-matching or color-checking session should continue. A return value of true indicates the session should be aborted--for example, the user may be holding down the Command-period keys.

DISCUSSION

Your MyCMBitmapCallBackProc function allows your application to monitor the progress of a color-matching or color-checking session for a bitmap or a pixel map. Your function can also terminate the matching or checking operation.

Your callback function is called by the CMM performing the matching or checking process if your application passes a pointer to your callback function in the progressProc parameter when it calls one of the following functions: CWMatchPixMap (page 3-116), CWCheckPixMap (page 3-118), CWMatchBitmap (page 3-120), and CWCheckBitMap (page 3-123).

The CMM used for the color-matching session calls your function at regular intervals. For example, the Apple CMM calls your function approximately every half-second unless the color matching or checking occurs in less time; this happens when there is a small amount of data to match or check.

Each time the ColorSync Manager calls your function, it passes to the function any data stored in the reference constant. This is the data that your application specified in the refCon parameter when it called one of the color-matching or checking functions.

For large bitmaps and pixel maps, your application could display an indicator to users, such as a progress thermometer, to register how much has been completed and how much remains. If your application were to do this, for example, you could use the reference constant to pass the dialog box's window reference to the callback function.

To terminate the matching or checking operation, your function should return a value of true. Because pixel-map matching is done in place, an application that allows the user to terminate the process should revert to the prematched image to avoid partial mapping.

For bitmap matching, if the matchedBitMap parameter of the CWMatchBitmap function specifies NULL, to indicate that the source bitmap is to be matched in place, and the application allows the user to abort the process, you should also revert to the prematched bitmap if the user terminates the operation.

Each time the ColorSync Manager calls your progress function, it passes a byte count in the progress parameter. The last time the ColorSync Manager calls your progress function, it passes a byte count of 0 to indicate the completion of the matching or checking process. You should use the 0 byte count as a signal to perform any cleanup operations your function requires, such as filling the thermometer or progress bar to completion to indicate to the user the end of the checking or matching session, and then removing the dialog box used for the display.