Sections on this Page
Plug-in Entry Point
A plug-in host calls a plug-in module in response to a user action. Generally, executing a user command results in a series of calls from the plug-in host to the plug-in module. All calls from the host to the module are done through a single entry point, the main() routine of the plug-in module. The prototype for the main entry point is:
#if MSWindows
void ENTRYPOINT (
short selector,
void* pluginParamBlock,
long* pluginData,
short* result);
#else
pascal void main (
short selector,
Ptr pluginParamBlock,
long* pluginData,
short* result);
#endif
selector
The selector parameter indicates the type of operation requested by the plug-in host. Selector=0 always means display an About box. Other selector values are discussed in later chapters for each type of plug-in module.
A plug-in’s main function is typically a switch statement that dispatches the pluginParamBlock, pluginData, and result parameters to different handlers for each selector that the plug-in module responds to. The example plug-in modules show one style of dispatching to selector handlers.
pluginParamBlock
The pluginParamBlock parameter points to a large structure that is used to pass information back and forth between the host and the plug-in module. The fields of this parameter block change depending on the type of plug-in module. Refer to the individual plug-in modules types (Plug In Modules) for descriptions of the parameter block for each type of plug-in module.
pluginData
The pluginData parameter points to a long integer (32-bit value), which Photoshop maintains for the plug-in module across invocations.
One standard use for this field is to store a handle to a block of memory used to reference the plug-in’s "global" data. It is zero the first time the plug-in module is called.
result
The result parameter points to a short integer (16bit value). Each time a plug-in module is called, it must set result; do not count on the result parameter containing a valid value when called. Returning a value of zero indicates that no error occurred within the plug-in module’s code.
Error reporting
The plug-in module may return standard operating system error codes, or report its own errors, in which case it can return any positive integer.
Returning a non-zero number in the result field indicates to the plug-in host that some sort of error occurred. It may also indicate that the user cancelled the operation somewhere during execution of the plug-in.
Returning a positive value indicates the plug-in encountered an error and an appropriate error message has already been displayed to the user. If the user cancels the operation in any way, the plug-in should return a positive value without reporting an error to the user.
Returning a negative value means that the plug-in encountered an error, and the plug-in host should display its standard error dialog.
The following table shows the common error code ranges used by the different types of plug-in modules, as well as some commonly used examples and their values. Refer to the header files and specific chapter for the plug-in type you’re designing for more details.
Error codes
| Module | Error Range | Definitions | Value |
| Color Picker | -30800 to -30899 | pickerBadParameters | -30800 |
| Import | –30000 to –30099 | acquireBadParameters
acquireNoScanner
acquireScanner | -30000
-30001
-30002 |
| Export | –30200 to –30299 | exportBadParameters
exportBadMode | -30200
-30201 |
| Filter | –30100 to –30199 | filterBadParameters
filterBadMode | -30100
-30101 |
| Format | –30500 to –30599 | formatBadParameters
formatBadMode | -30500
-30501 |
| Selection | –30700 to –30799 | selectionBadParameters
selectionBadMode | -30700
-30701 |
| General Errors | –30900 to –30999 | errPlugInHostInsufficient
errPlugInPropertyUndefined
errHostDoesNotSupportColStep
errInvalidsamplePoint | -30900
-30901
-30902
-30903 |
The plug-in may also return Mac and Windows operating system error codes to the plug-in host. In PITypes.h, several common Mac OS error codes are defined for use in Windows, simplifying cross-platform programming.
About boxes
All plug-ins should respond to a selector value of zero, which means display an About box. The about box may be of any design. To fit in smoothly with the Adobe Photoshop interface, follow these conventions:
- The About box should be centered on the main (menu bar) screen, with 1/3 of the remaining space above the dialog, and 2/3 below. Be sure to take into account the menu bar height. System 7 or later of the Mac OS has a flag in the
'DLOG' resource that automatically positions the about box in the window.
- The window should not have an OK button, but should instead respond to a click anywhere in its dialog.
- It should respond to the return and enter keys.
- Note:
- Adobe PhotoDeluxe has very specific dialog design requirements. A sample About box is available in the
Photoshop-WDEF folder in the Examples folder.
The parameter block at selectorAbout
On the about selector call, the parameter block for the module is not passed. Instead, in its place, a structure of type AboutRecord is passed. Because of this, access to any of the standard parameters for the module during selectorAbout is unavailable.
Multiple plug-ins and selectorAbout
When Photoshop attempts to bring up the about box for a plug-in module, it makes the about box selector call to each of the plug-ins in the same file. If there is more than one plug-in compiled in a file, only one of them should respond to the call by displaying an about box that describes all the plug-ins. All other plug-in modules should ignore the call and return to the plug-in host.
