Non-Suite Callbacks

These callbacks are found directly in the various plug-in parameter block structures. More...

Non-Suite Callbacks
typedef MACPASCAL Boolean(*	TestAbortProc )(void)
	Provides a mechanism to allow the user to abort the operation of the plug-in.
typedef MACPASCAL void(*	ProgressProc )(int32 done, int32 total)
	Provides a mechanism for the plug-in to update progress indicators.
typedef MACPASCAL void(*	HostProc )(int16 selector, intptr_t *data)
	Contains a pointer to a host-defined function.
typedef MACPASCAL int32(*	SpaceProc )(void)
	Examines imageMode, imageSize, depth, and planes and determines the number of bytes required to hold the image.
typedef MACPASCAL void(*	ProcessEventProc )(void *event)
	Allows Mac OS plug-in modules to pass standard EventRecord pointers to Photoshop.
typedef MACPASCAL OSErr(*	DisplayPixelsProc )(const PSPixelMap *source, const VRect *srcRect, int32 dstRow, int32 dstCol, void *platformContext)
	Displays pixels in various image modes given a block of pixels to display.
typedef MACPASCAL OSErr(*	AdvanceStateProc )(void)
	Allows the plug-in to ask the host to update, i.e., "advance the state of", the various data structures used for communicating between the host and the plug-in.
typedef MACPASCAL OSErr(*	ColorServicesProc )(ColorServicesInfo *info)
	Provides a plug-in module with access to common color services within Photoshop.

---

Detailed Description

These callbacks are found directly in the various plug-in parameter block structures.

For more information, see Using Non-Suite Callbacks.

---

Typedef Documentation

typedef MACPASCAL Boolean(* TestAbortProc)(void)

Provides a mechanism to allow the user to abort the operation of the plug-in.

A plug-in should call this function several times a second during long operations. If the user has requested to abort the operation, the plug-in should return a positive error code. As a side effect, this changes the cursor to a watch and moves the watch hands periodically.

Returns:

TRUE if the user has requested to abort the operation.

typedef MACPASCAL void(* ProgressProc)(int32 done, int32 total)

Provides a mechanism for the plug-in to update progress indicators.

The plug-in can call this procedure periodically to update a progress indicator. This procedure should only be called in the actual main operation of the plug-in, not while long operations are executing during the preliminary user interface. Photoshop automatically suppresses display of the progress bar during short operations.

Parameters:

done	The number of operations completed.
total	The total number of operations.

typedef MACPASCAL void(* HostProc)(int16 selector, intptr_t *data)

Contains a pointer to a host-defined function.

A plug-in should verify the host signature (in the parameter blocks hostSig field) before calling this procedure. This provides a mechanism for hosts to extend the plug-in interface to support application-specific features.

Parameters:

selector	The operation to perform.
data	Data provided for the operation.

Note:

Adobe Photoshop versions 3.0.4 and later do not perform any tasks in this callback. Earlier versions of Photoshop used Host for private communication between Photoshop and some plug-in modules.

typedef MACPASCAL int32(* SpaceProc)(void)

Examines imageMode, imageSize, depth, and planes and determines the number of bytes required to hold the image.

Returns:

The number of bytes of scratch disk space required to hold the image, or -1 if the values are not valid.

Note:

This callback is only available to Acquire (Import) plug-in modules.

typedef MACPASCAL void(* ProcessEventProc)(void *event)

Allows Mac OS plug-in modules to pass standard EventRecord pointers to Photoshop.

For example, when a plug-in receives a deactivate event for one of the Photoshop windows, it should pass this event on to Photoshop. This routine can also be used to force Photoshop to update its own windows by passing relevant update and NULL events.

Note:

This callback is only useful on Mac OS; a call to ProcessEventProc in the Adobe Photoshop for Windows does nothing.

typedef MACPASCAL OSErr(* DisplayPixelsProc)(const PSPixelMap *source, const VRect *srcRect, int32 dstRow, int32 dstCol, void *platformContext)

Displays pixels in various image modes given a block of pixels to display.

The routine does the appropriate color space conversion and copies the results to the screen with dithering. It leaves the original data intact. To suppress the watch cursor during updates, see propWatchSuspension in the Properties suite.

Parameters:

source	Describes a block of pixels to display.
srcRect	Indicates the rectangle of the source pixel map to display.
dstRow	Provides the coordinates of the top-most destination pixel in the current port (i.e., the destination pixel defined by dstRow and dstCol corresponds to the top-left pixel in srcRect). The display routines do not scale the pixels, so specifying the top left corner is sufficient to specify the destination.
dstCol	Provides the coordinates of the left-most destination pixel in the current port.
platformContext	On Windows, should be the target hDC, cast to an unsigned32. Not used on Mac OS (Carbon) since the display routines simply assume that the target is the current port. Cast to PSPlatformContext * on Cocoa systems. See description for PSPlatformContext

Returns:

If successful, returns noErr. Non-success is generally due to unsupported color modes.

typedef MACPASCAL OSErr(* AdvanceStateProc)(void)

Allows the plug-in to ask the host to update, i.e., "advance the state of", the various data structures used for communicating between the host and the plug-in.

Use AdvanceStateProc where you expect a plug-in to be called repeatedly. For example, a scanner module that scans and delivers images in chunks. When working with large images (larger than available RAM), plug-ins should process the image in pieces. Without AdvanceStateProc, a plug-in is called from, and returns to, the host for each chunk of data. Each repeated call must go through your plug-ins main() entry point. With AdvanceStateProc, a plug-in can complete its general operation within a single call from the plug-in host. This does not include setup interaction with the user, or normal cleanup.

The precise behavior of this callback varies depending on what type of plug-in module is executing. Refer to specific plug-in modules for information on how to use this callback.

Returns:

noErr if successful; a non-zero error code if unsuccessful.
If the user cancels by pressing Escape in Windows, or Command-period in Mac OS, AdvanceStateProc returns userCanceledErr (-128).

Note:

If an error is returned, the plug-in should not call AdvanceStateProc again, but instead return the error code to the plug-in host back through main().

AdvanceState, Buffers, Proxies, and DisplayPixels
Proxies really put AdvanceState to work, because if the plug-in allows the user to drag around an image, the plug-in is constantly updating and asking for more image data. To keep the lag time down, and the update watch from appearing often in DisplayPixels, keep these items in mind:

• AdvanceState buffers as much of the image as it can, so make the first call for inRect as large as possible. In subsequent calls, as long as the request falls within inRect, the image data comes right out of the buffer.
• As soon as the plug-in sets inRect=0,0,0,0 or it calls for one pixel outside of the buffer area (the first calling rect it passed) AdvanceState flushes the buffer and loads new image data from the VM system.

typedef MACPASCAL OSErr(* ColorServicesProc)(ColorServicesInfo *info)

Provides a plug-in module with access to common color services within Photoshop.

It can be used to perform one of four operations:

• choose a color using the users preferred color picker (the Photoshop color picker, the Systems, or any Color Picker plug-in module),
• convert color values from one color space to another,
• return the current sample point,
• return either the foreground or background color.

See Color Picker Module for information about the Color Picker plug-in module type.

Parameters:

info	The structure passed to color services to define the type of access.

Note:

ColorServicesProc has a bug in versions of Photoshop prior to 3.0.4. When converting from one color space to another they return error paramErr=-50 and convert the requested color to RGB, regardless of the target color space. ColorServices also may have errors converting between any color space and Lab, XYZ, or HSL. RGB, CMYK, and HSB have been proven and are correct, but check the numbers on the others before relying on them.