Carbon


CMBitmapCallBackProcPtr

Header: CMApplication.h Carbon status: Supported

Defines a pointer to a bitmap callback function. Your bitmap callback function reports on the progress of a color-matching or color-checking session being performed for a bitmap or a pixel map.

typedef Boolean(* CMBitmapCallBackProcPtr) (
    SInt32 progress, 
    void *refCon
);

You would declare your function like this if you were to name it MyCMBitmapCallBackCallback:

Boolean MyCMBitmapCallBackCallback (
    SInt32 progress, 
    void *refCon
);
Parameter descriptions
progress

A byte count that begins at an arbitrary value when the function is first called. On each subsequent call, the value is decremented by an amount that can vary from call to call, but that reflects how much of the matching process has completed since the previous call. If the function is called at all, it will be called a final time with a byte count of 0 when the matching is complete.

refCon

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

function result

False indicates the color-matching or color-checking session should continue. True indicates the session should be aborted—for example, the user may be holding down the Command–period keys.

DISCUSSION

Your MyCMBitmapCallBack 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: CWCheckBitmap, CWMatchBitmap, CWCheckPixMap, and CWMatchPixMap. Note that your callback function may not be called at all if the operation completes in a very short period.

The CMM used for the color-matching session calls your function at regular intervals. For example, the default 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 can display a progress bar or other indicator to show how much of the operation has been completed. You might, for example, use the reference constant to pass to the callback function a window reference to a dialog box. You obtain information on how much of the operation has completed from the progress parameter. The first time your callback is called, this parameter contains an arbitrary byte count. On each subsequent call, the value is decremented by an amount that can vary from call to call, but that reflects how much of the matching process has completed since the previous call. Using the current value and the original value, you can determine the percentage that has completed. If the callback function is called at all, it will be called a final time with a byte count of 0 when the matching is complete.

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 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.


© 2000 Apple Computer, Inc. (Last Updated 7/17/2000)