Writing Import Plug-ins

Import plug-in modules are used to capture images from add-on hardware, such as scanners or video cameras, and put these images into new Photoshop document windows.

Import modules can also be used to read images from unsupported file formats, although file format modules often are better suited for this purpose. File format modules are accessed directly from the Open command, while Import modules use the Import sub-menu.

For descriptions of the sample Import plug-ins provided with the SDK, see Import Samples.

The calling sequence for Import modules is a little more complex than other types of plug-in modules. In a single invocation, Import modules are capable of capturing multiple images and creating multiple new Photoshop document windows. Because captured images may be large, each capture may require multiple exchanges between the host and the module.

When the user invokes an Import plug-in module by selecting its name from the Import submenu, Photoshop calls it with the sequence of selector values shown in the figure below. The actions the Import plug-in needs to take for these selectors are discussed in more detail in Import Modules.

Note:

Your plug-in should validate the contents of its globals and parameters whenever it starts processing if there is a danger of it crashing from bad parameters.

Special Error Handling for Import Plug-ins

In the event of any error during import, the document being imported is discarded.

Advance State and Import Modules

The AdvanceStateProc callback allows the plug-in the drive the interaction through the inner acquireSelectorContinue loop without actually returning to the plug-in host. In the Import module, the AdvanceStateProc can only be called from the acquireSelectorContinue handler.

If the host returns an error, then the plug-in should treat this as an error condition and return the error code when returning from the acquireSelectorContinue handler.

Import Modules and Scripting

The scripting system passes its parameters at every selector call. While it is possible to use the scripting system to store all your parameters, for backwards compatibility, it is recommended you track your parameters with your own globals. Once your globals are initialized, you should read your scripting-passed parameters and override your globals with them. The most effective way to do this is:

1. First call a ValidateMyParameters routine to validate (and initialize if necessary) your global parameters.
2. Then call a ReadScriptingParameters routine to read the scripting parameters and then write them to your global structure.

This way, the scripting system overrides your parameters, but you can use the initial values if the scripting system is unavailable or has parameter errors, and you can use your globals to pass between your functions.

Scripting at acquireSelectorFinish

If your plug-in is scripting-aware and it has changed any initial parameters, it should pass a complete descriptor back to the scripting system in the PIDescriptorParameters structure.

Multiple Import

The plug-in host can loop back to acquireSelectorStart after completing acquireSelectorFinish to begin importing another image for multi-image importing if the following conditions are true:

• the plug-in host supports multiple imports (Photoshop version 3.0 and later)
• the plug-in module has set AcquireRecord::acquireAgain=TRUE, and
• the acquireSelectorContinue loop finished normally, meaning no error was returned and the loop ended with AcquireRecord::data = NULL.

The plug-in host can also loop back to acquireSelectorStart to begin acquiring another image if these alternate conditions are true:

• the plug-in host supports multiple imports,
• the plug-in host set canFinalize=TRUE,
• the plug-in module set AcquireRecord::wantFinalize=TRUE and AcquireRecord::acquireAgain=TRUE, and
• the acquireSelectorContinue loop finished with a result code >= 0 or a result code of userCanceledErr.

Batch Import

Batch Importing is a feature of the scripting system that automatically processes multiple files through your scripting-aware Import module. If your Import module is scriptable, Batch Importing is handled completely by the host, which passes parameters and control to your Import plug-in as part of a script. Batch Import is available from the Actions palette.

Batch Import versus Multiple Import

While Multiple Import is an internal feature available in the Import module, Batch Import is based on the host scripting mechanism. Here are some issues that should help you determine whether to implement Multiple Import or Batch Import:

• Batch Import is transparent if your plug-in is scripting-aware. This means the plug-in needs only export its parameters to the scripting system and read them in at call-time to be able to be controlled by Batch Import. Batch Import of single imports would be the most appropriate for single-sheet scanners, for instance. Batch Import triggers when your user interface is closed. This means if you do a multiple import and leave your user interface up, the scripting system does not take control until after your multiple import is done.
• Multiple Import is always controlled by the plug-in. It allows the plug-in to return multiple images with one invocation, versus Batch Import which calls the plug-in new for every image. The scripting system only takes control after the plug-in's user interface is closed. The plug-in can hide its user interface during the Multiple Import loop, between the acquireSelectorFinish and next acquireSelectorStart call, for the scripting system to process that image and return to plug-in control.

If you decide to implement Multiple Import but still want your plug-in to be scripting aware, then we recommend you follow the GradientImport example from the SDK, and export your Multiple Import commands as a single scripting event. Batch Import of a module that does Multiple Import would be the most appropriate for digital cameras, for instance, where the user wants to grab every other image in the camera's buffer.